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PREFACE 


MANUAL  OBJECTIVES 

The  RSX-llM/M-PLUS  Guide  to  Program  Development  introduces  the  program 
develcpment  environment  on  the  RSX-llM  and  RSX-llM-PLUS  systems.  It 
provides  a  synopsis  of  the  information  immediately  useful  in  getting 
started  in  the  program  development  process.  The  book  also  gives  ar 
overview  of  the  software  environment  and  some  guidelines  on  program 
design. 


INTEMur^  AUDISNCE 

This  book  is  intended  for  the  person  who  is  already  familiar  with  the 
general,  basic  operations  of  an  RSX-llM/M-PLUS  system:  gaining  access 
to  the  system,  using  the  terminal  and  related  devices,  and  requesting 
simple  Executive  services  through  the  command  interface.  The  greater 
part  of  the  book  addresses  assembly  language  programming  because  that 
language  is  the  one  provided  with  all  systems.  Included  is  one 
chapter  summarizing  the  program  development  procr-'^reci  for  a 
high-level  language,  PDP-11  FORTRAN  IV.  However,  most  of  the  topics 
covered  for  the  assembly  language  programmer  —  using  a  text  editor, 
creating  an  executable  image,  using  library  facilities  —  apply  to 
programmers  using  any  computer  language. 

If  you  are  not  familiar  with  the  general,  basic  operations  of  the 
system,  you  should  first  read  the  Introduction  ^  RSX-llM  and 
n"X-llM-PLUS.  This  book  describes  how  to  access  tEe  system,  use  a 
terminal,  and  use  the  system  command  interface. 


STRUCTURE  OF  THIS  DOCUMENT 

This  guide  is  meant  to  be  read  as  you  use  the  system.  For  this 
reason,  the  examples  are  presented  in  an  order  that  you  can  follow  at 
the  terminal.  Rather  than  demonstrate  the  complexity  of  the  system, 
these  examples  are  debigned  to  demonstrate  practical  program 
development  operations. 

This  guide  is  also  meant  to  be  used  with  other  manuals  in  your 
documentation  set.  Toward  this  end,  a  selection  of  further  reading 
material  is  listed  in  the  last  section  of  each  chapter.  By  using  this 
guide,  then,  you  can  become  increasingly  familiar  with  other,  more 
advanced  manuals  until  you  need  not  refer  to  this  introductory  text 
except  as  a  refresher. 
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PREFACE 

The  infornation  in  this  book  is  organized  into  seven  chapters,  as 
follows: 

•  Chapter  1,  The  Program  Development  Environment,  introduces  the 
software  and  hardware  on  which  you  develop  programs. 

•  Chapter  2,  Creating  MACRO-11  Source  Files,  describes  how  to 
create  an  assembly  language  source  program  using  a  skeleton 
file  and  text  editor. 

•  Chapter  3,  Assembling  and  Correcting  a  Program  Module, 
describes  how  to  usa  the  MACRO-11  Assembler  to  generate  an 
object  module. 

•  Chapter  4,  Building  and  Testing  a  Task,  describes  how  to  use 
the  Task  Builder  to  link  object  modules  to  create  a  loadable 
task  image. 

•  Chapter  5,  Using  Debugging  Aids,  introduces  debugging  aids  and 
discusses  how  to  use  them. 

•  Chapter  6,  Creating  and  Using  Program  Libraries,  describes  how 
to  create  and  maintain  a  library  of  macro  source  statements 
and  a  library  of  object  module  subroutines. 

•  Chapter  7,  FORTRAN  IV  Procedures,  briefly  introduces  the 
FORTRAN  IV  program  development  process. 


ASSOCIATED  DOCUMENTS 

As  mentioned  above,  documents  recommended  for  further  reading  are 
listed  at  the  end  of  each  chapter.  In  addition,  the  RSX-llM 
Information  Directory  and  Index  and  the  RSX-llM-PLUS  Information 
DirectoTy  and  Index  list  and  describe  aTI  the  documents  in  the 
documentation  sets  for  each  system. 


CONVENTIONS  USED  IN  THIS  DOCUMENT 

Throughout  this  book,  symbols  and  other  notation  conventions  are  used 
to  represent  keyboard  characters,  to  convey  textual  information,  and 
to  otherwise  ease  the  presentation  of  material.  The  symbols  and 
conventions  used  are  explained  below. 

Convention  Meaning 

f»5()  A  1-  to  3-character   symbol   indicates   that 

you  press  a  key  on  the  terminal;  for 
example,  (E)  indicates  the  RETURN  key  and  © 
indicates  the  LINE  FEED  key. 

C!RWi  The  symbol  CfUM      indicates   that  you  must 

press  the  key  labeled  CTRL  while  you 
simultaneously  press  another  key;  for 
example,  @@  indicates  the  CTRL  and  0 
keys.  In  examples,  this  control  key 
sequence  is  shewn  as  "x;  for  example,  "0 
indicates  the  result  of  typing  c"m 
because  that  is  how  the  system  echoes  many 
control  key  combinations. 


^^^ 


Vlll 
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Convention 


N«anlnq 

Th«  circunflex  character,  appearing  with 
another  character,  represents  the  system 
response  to  receiving  a  control  character 
(CTRL/n) .  For  example,  when  you  type  the 
CTRL/Z  combination  while  running  some  system 
tasks,  the  system  echoes  "^Z.  (On  some 
terminals,  the  circumflex  is  replaced  by  the 
up-arrow  (f)  character.) 


"print"  and  "type' 


l>ICR> 


DCL> 


red  ink 


As  these  words  are  used   in   the   text, 
system  prints  and  the  user  types. 


the 


This  is  the  explicit  prompt  of  the  Monitor 
Console  Routine  (MCR) ,  one  of  the  command 
Interfaces  used  on  RSX-llM  and  RSX-llM-PLUS 
systems « 

This  is  the  explicit  prompt  of  the  DIGITAL 
Command  Language  (DCL) ,  one  of  the  command 
interfaces  used  on  RSX-llK  and  RSX-llM-PLUS 
systems. 

A  right-angle  bracket  is  the  system   command 

interface   prompting  character.   Whenever 

control   is   returned  to   the    user    task 

terminal  and  you  can  type  input,  the  prompt 
appears. 

RSX-llM  and  RSX-llM-PLUS  systems  can  have 
one  or  more  command  line  interpreters 
(CLIs) .  All  systems  include  MCR  and  many 
systems  include  DCL.  To  determine  which 
command  interface  your  terminal  has,  type 
the  CTRL/C  combination  and  the  explicit 
prompt  (either  NCR>  or  DCL>)  will  appear. 

Color-highlighted  information  in  examples 
indicates  information  that  you  type. 
Information  in  examples  not  in  the 
contrasting  color  constitutes  computer 
output. 

Commas  in  commands  separate  parameters. 
They  also  indicate  positional  entries  on  a 
command  line. 

A  period  in  a  file  specification  separates 
the  file  name  and  the  file  type. 


A  semicolon 
separates  the 
number. 


in   a   file   specification 
file  type  and  file  version 
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CHAPTER  1 
THE  PROGRAM  DEVELOPMENT  ENVIRONMENT 


This  chapter  introduces  the  software  and  hardware  that  you  typically 
need  to  develop  programs  on  an  RSX-llM  or  RSX-llM-PLUS 
multiprogramming  system.  Its  aim  is  to  orient  you  to  the  environment 
in  which  you  will  be  working.  The  remaining  chapters  in  the  guide 
further  describe  and  illustrate  how  to  use  the  tools  and  facilities 
introduced  in  the  following  sections. 


1.1   SOFTWARE  TOOLS 

RSX-llM  and  RSX-llM-PLUS  make  software  tools  available  as  executable 
entities  called  system  tasks.  The  system  tasks  include  one  or  more 
editors,  the  MACRO-11  Assembler,  the  RSX-llM/M-PLUS  Task  Builder, 
several  aids  to  debugging,  and  a  number  of  utility  tasks.  Your  system 
may  also  include  one  or  more  high-level  language  compilers  or 
interpreters.  These  elements  combined  form  the  program  development 
environment.  In  general,  the  system  manager  makes  these  tasks 
accessible  to  you  by  Installing  them  on  the  system.^ 

To  invoke  a  task,  you  need  not  know  where  the  task  resides.  The 
RSX-llM  and  RSX-llM-PLUS  operating  systems  offer  two  command  line 
Interpreters  for  communicating  with  the  system  and  invoking  system 
services^  These  are  the  Moni';or  Console  Routine  (MCR)  and  the  DIGITAL 
Command  Language  (DCL) .  MCR  is  included  in  all  RSX-llN/M-PLUS 
systems,  whereas  DCL  is  optional.  Each  terminal  is  set  to  recognize 
either  MCR  or  DCL  upon  logging  in. 


1.1.1  Command  Line  Interpreters 

RSX-llM/M-PLUS  systems  can  have  one  or  more  command  line  Interpreters 
(CLIs) .  All  systems  include  MCR.  Many  systems  include  DCL,  and  some 
systems  include  user-written  CLIs.  Both  MCR  and  DCL  include  commands 
to  invoke  most  system  tasks  and  utilities  to  set  and  display  certain 
system  characteristics.  In  general,  MCR  commands  invoke  tasks  such  as 
PIP,  a  utility  used  to  manipulate  files  (for  example,  copying  them). 
DCL  commands  specify  actions  directly,  as  in  the  COPY  command  or  the 
TYPE  command. 

MCR  is  the  fundamental  CLI  for  the  RSX-llM/M-PLUS  operating  systems. 
From  an  MCR  terminal,  tasks  installed  with  names  in  the  form  ...abc 


1.  Or>  systems  with  fewer  resources,  some  tasks  may  not  be  permanently 
installed.  Such  systems  may  use  the  "flying  install"  feature,  or 
require  you  to  use  some  form  of  the  RUN  command  to  install  system 
tasks  temporarily.  See  your  system  manager  for  further  information. 
This  manual  assumes  that  all  tasks  are  Installed. 
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can  be  invoked  simply  by  typing  the  abc  portion  of  the  task  name. 
Most  system  tasks  and  utilities  are  installed  with  names  of  that  form. 
MCR  also  provides  commands  to  set  and  display  certain  system  and 
device  characteristics.  MCR  provides  the  most  direct  interface  with 
the  operating  system,  either  RSX-llM  or  RSX-llM-PLUS. 

DCL  is  an  optional  CLI  included  in  most  systems  with  heavy  terminal 
use.  Commands  in  DCL  are  English-like  words  and  follow  well-defined 
syntax  rules. 


You  are  not  required  to  use 
Usually,   you  need   type  on 
unique  command.   Most  exampl 
clarity,   but   you  should 
copy  of  your  terminal  activi 
use  much  shorter  forms  than 
able  to  shorten  any  command 
commands  ^nd  qualifiers  can 


the  full  form  of  DCL  commands,  however, 
ly  the  command  elements  required  to  form  a 
es  in  this  manu&l  are  in  full  format  for 
keep  in  mind  that  unless  you  are  keeping  a 
ty  for  possible  future  reference,  you  can 
those  in  the  examples.  You  will  always  be 
or  qualifier  to  four  characters.  Most 
be  entered  with  even  fewer  characters. 


DCL  prompts  you  for  all  required  command   elements.    If  you  do  not 

understand  a  prompt,  type  in  a  question  mark  (?) .   DCL  will  print  HELP 

text  explaining  the  format  and  function  of  the  command  and  then 
reprompt  you  for  required  input. 

DCL  is  actually  a  CLI  task  that  translates  DCL  commands  into  MCR 
commands  for  execution  by  the  system.  The  DCL  SET  DEBUG  command 
displays  the  MCR  translation  for  any  DCL  command  on  your  terminal 
without  executing  the  command.  Depending  on  the  kind  of  use  you  make 
of  your  system  and  the  nature  of  your  system,  you  may  find  it  more 
convenient  to  use  one  CLI  or  the  other,  or  both.  All  nonprivileged 
system  functions  are  available  directly  from  DCL,  but  some  privileged 
functions  are  not.  All  program  development  facilities  and  all  common 
utility  fuikctions  are  available  from  DCL. 

Your  teritt'nal  is  set  to  either  MCR  or  DCL.  You  can  determine  which  by 
typing  a  CTRL/C.   The  explicit  prompt  identifies  the  CLI. 

You  can  change  from  DCL  to  MCR,  or  vice  versa,  at  any  time.  The  DCL 
command  SET  TERM  MCR  switches  you  from  DCL  to  MCP.  The  MCR  command 
SET  /DCL-TI:  switches  you  from  MCR  to  DCL.  In  addition,  you  can 
enter  a  single  DCL  command  from  an  MCR  terminal  with  the  DCL  command 
or  enter  a  single  MCR  command  from  a  DCL  terminal  with  the  MCR 
command.   For  example,  the  following  commands  have  the  same  effect: 

DCL>MCR  PIP  Tl!=filespec 

MCR>DCL  TYPE  filespec 


NOTE 

As  shipped,  DCL  includes  the  SET  DEBUG 
and  MCR  commands.  These  commands  may  be 
disabled  at  some  installations.  As 
shipped,  DCL  also  rejects  any  commands 
it  does  not  recognise,  but  some 
installations  may  have  enabled  a  feature 
that  allows  any  command  unrecognized  by 
DCL  to  "fall  through"  to  MCR  for 
interpretation.  See  your  system  manager 
for  more  information  on  the  limits  of 
DCL  at  your  installation. 


The  RSX-llM/M-PLUS  Guide  to  Program  Development  concentrates  on   the 
actual   program  development  process  and  not  on  DCL  or  MCR.   However, 
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some  of  the  program  development  facilities  require  different  commands 
In  DCL  and  MCR.  In  particular,  the  commands  for  the  MACRO-11 
Assembler,  the  Librarian  Utility  Program,  and  the  RSX-llM/M-PLUS  Task 
Builder  are  different.  While  this  will  probably  not  interfere  with 
your  use  of  the  system,  it  may  be  confusing  at  first.  The  programming 
demonstrations  in  this  manual  are  documented  first  using  DCL  commands, 
then  once  again  using  MCR  commands.  This  duplication  enables  you  to 
see  the  differences  between  DCL  and  MCR. 


1.1.2  Text  Editors 

A  text  editor  is  the  means  by  which  you  create  a  source  code  file. 
Most  RSX-llM/N-PLUS  systems  include  the  Line  Text  Editor  EDI  and  the 
DEC  Standard  Editor  EDT.  Both  of  these  editors  are  interactive 
editing  programs  that  enable  you  to  enter  ASCII  text  at  a  terminal  and 
store  the  text  in  a  disk  file.  They  also  let  you  access  text  in  a 
disk  file;  examine,  delete,  end  change  text;  and  insert  new  text. 
The  disk  file  is  then  used  as  input  to  other  tasks  in  further  steps  of 
the  program  development  process. 

EDI  is  introduced  in  this  manual  and  further  documented  in  the 
RSX-llM/M-PLUS  Utilities  Manual.  EDT  is  introduced  in  the 
Introduction  to  RSX-llM  and  RSX-llM-PLUS  and  further  documented  in  the 
EDT  Editor  ManuaTI 

You  can  use  EDI  or  EDT  or  some  other  editor  found  at  your  installation 
with  the  examples  in  this  book.  DCL  users  invoke  an  editor  in  the 
following  manner: 

DCL>EDIT/EDI  filespec 

DCL>EDIT/EDT  filespec 

MCR  users  invoke  an  editor  in  the  following  manner: 

MCR>EDI  filespec 

MCR>EDT  filespec 

In  both  DCL  and  NCR,  the  EDT  command  line  can  include  other  command 
elements  to  invoke  special  features  of  EDT. 

EDI  may  be  the  only  editor  available  on  smaller  systems. 

EDI  is  a  single-pass,  line-oriented  editor.  In  its  typical  mode  of 
operation,  called  block  mode,  it  reads  from  a  disk  file  a  block  of 
text  —  as  much  text  as  will  fit  in  its  text  buffer.  You  perform 
editing  operations  on  text  in  the  EDI  buffer.  After  editing  text  in 
the  buffer,  you  request  the  editor  to  renew  the  buffer  with  the  next 
block  of  text.  To  change  text  in  a  previously  edited  buffer,  you  must 
close  the  current  editing  session,  open  the  file  again  by  reinvoking 
EDI,  and  read  from  the  beginning  of  the  file  to  the  block  of  text. 

Editing  functions  are  on  a  line-by-line  basis.  New  text  is  inserted 
into  the  buffer  one  line  at  a  time.  Current  text  in  the  buffer  is 
changed  by  your  locating  the  line  or  lines  on  which  EDI  must  make  the 
change. 

To  preserve  currently  existing  text,  EDI  performs  all  processing  on  a 
temporary  copy  of  the  file  being  edited.  As  you  renew  text  in  the 
buffer,  EDI  writes  the  edited  text  to  a  temporary  file.  This  action 
has  two  advantages  and  one  drawback.  First,  the  current  version  of 
your  text  file  is  always  left  Intact.  Second,  when  you  exit  from  the 
editing   session,   you  have  the  option  of  storing  the  edited  file  in  a 
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new  version  of  the  old  file  or  of  creating  an  entirely  new  file  (that 
is,  one  with  a  different  name  and  version  number) .  The  drawback  of 
the  temporary  file  is  that,  in  the  event  of  a  system  crash,  edits  yoj 
are  making  are  lost.  After  a  crash,  the  new  version  of  the  file  has  a 
zero  length  because  EDI  did  not  have  time  to  preserve  the  edits  from 
the  temporary  file. 


1.1.3  Assembly  Language 

RSX-llM  and  RSX-llM-PLUS  systems  support  many  programming  languages. 
However,  the  one  language  distributed  on  all  systems  is  the  PDP-11 
assembly  language,  MACRO-11.  MAC  is  the  task  that  assembles  NACRO-11 
language  files.  It  accepts  a  disk  source  input  file  in  ASCII  format 
and  can  create  a  relocatable  object  module  and  a  listing  file  of  the 
source  language.  The  object  module  contains  all  the  object  records 
and  relocation  information  needed  to  link  with  other  object  modules. 
All  symbo''.  definition  done  by  the  assembler  has  a  base  address  of 
zero.  The  allocation  of  virtual  addresses  and  relocation  is  left  for 
the  task-building  process.  ^ 

DCL  user!!  invoke  MAC  with  the  MACRO  command.  MCR  users  invoke  MAC 
with  the  MAC  command. 

Source  input  to  MACRO-11  consists  of  free-format  statements,  each  line 
of  input  containing  a  single  statement.  Input  statenents  are  either 
PDP-11  instructions,  MACRO-11  Assembler  directives,  macro  calls,  or 
direct  assignments.  Statements  can  contain  labels  to  allow  control  to 
change  locally  (within  the  module)  or  to  enable  control  to  be  passed 
between  modules  (globally) . 

Source  input  usually  contains  user-defined  symbols,  which  are  either 
local  or  global.  A  local  symbol  is  defined  in  the  current  source  file 
and  is  referenced  only  within  the  current  file.  A  global  symbol  is 
defined  in  one  source  file  but  can  be  referenced  in  one  or  more  other 
source  files. 

The  assembler  allows  you  to  use  both  local  and  global  symbols  as 
labels  for  statements.  When  a  global  symbol  appears  as  a  label,  the 
related  statement  is  referred  to  as  an  entry  point  (that  is,  a  point 
at  which  other  modules  can  transfer  control  to  the  curi^-'tt  object 
module) .  You  can  use  local  symbols  as  statement  labels  to  define 
points  to  which  control  transfers  within  an  object  module. 

The  assembler  evaluates  all  local  symbol  definitions  in  a  source  file. 
Any  symbols  remaining  undefined  are  classified  as  global.  Thus,  after 
an  assembly,  all  local  symbols  are  assigned  relative  locations,  b..t 
the  module  may  contain  references  for  which  definitions  must  be 
supplied.  The  resolution  of  these  references  is  left  for  the 
task-building  process. 

Assembler  directives  in  a  source  file  allow  you  to  perform  operations 
such  as  the  follow'ng: 

.■:>    e   Program  sectioning 

•  Listing  control 

e   Conditional  assembly 

•  Data  storage 

Program  sectioning  allows  code  or  data  within  an  object  module  to  be 
overlaid  by,  or  concatenated  with,  code  or  data  in  other  object 
modules  or  in  noncontiguous  locations  within  the  same  module.   Program 
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sectioning  is  especially  useful  where  convenient  physical  ordering 
differs  from  logical  reference  ordering  (for  example,  in 
table-generating  macro  statements) .  Listing  control  directives  enable 
documentation  features  such  as  listing-heading  lines,  listing-page 
formatting,  and  table  of  contents  generation.  Conditional  assembly 
directivec  < , low  optional  omission  or  inclusion  of  lines  of  code  or 
user-definet  symbols.  Using  data  storage  directives,  you  can  control 
the  size  and  contents  of  data  areas. 

Special  statements  called  macro  directives  allow  you  to  reference  a 
predefined  symbol  that  causes  the  assembler  to  expand  a  single  line 
source  statement  into  multiple  lines  of  code  or  data  and  insert  the 
assembled  result  in  the  object  module.  Such  macro  symbols  are 
typically  used  for  recurring  coding  sequences.  The  insertion  of  the 
code  sequ'snce  occurs  at  each  point  you  refer  to  the  macro  symbol. 
Definitions  for  such  macro  symbols  can  occur  in  the  source  file  itself 
or  can  reside  in  a  macro  library.  Generally,  you  placo  infrequently 
used  macro  definitions  in  the  source  file  that  invokes  them,  and  store 
frequently  used  macro  definitions  in  a  macro  library.  The  Executive 
and  file-processing  services  are  made  available  to  the  program  through 
macro  sym^<>ls  that  are  defined  in  a  DIGITAL-supplied  macro  library. 

NACRO-11  is  a  z-pass  assembler.  During  the  first  pass,  the  assembler 
groups  all  symbols  as  either  local  or  global,  performs  statement 
generation,  locates  all  macro  symbols,  and,  if  necessary,  reads  the 
macro  definitions  from  libraries.  At  the  end  of  pass  1,  the  assembler 
must  have  processed  all  local  references  (such  as  all  undefined  global 
symbols)  that  are  to  be  resolved  by  the  Task  Builder. 

During  the  second  pass,  the  assembler  actually  generates  the  object 
module  and  listing  files,  flagging  with  an  error  code  in  the  listing 
file  those  source  statements  containing  errors.  If  you  requested  a 
cross-reference  listing  of  symbols,  the  assembler  also  generates  a 
request  for  the  Cross-Reference  Processor  (CRF)  to  create  the  proper 
information.   (CR?  is  introduced  in  Section  1.1.6  in  this  chapter.) 

The  MACRO-11  listing  file  provides  both  documentation  for  the  module 
and  a  tool  for  debugging  the  code.  As  a  reference  aid,  the  assembler 
generates  and  Includes  line  numbers  in  the  listing  for  each  statement 
in  the  source  file.  It  also  maintains  a  current  location  counter  for 
each  program  section  defined  in  the  source  file.  In  addition,  the 
listing  includes  a  symbol  table  showing  symbols,  their  attributes,  and 
their  values  if  known  at  assembly  time. 

The  location  counter  value  given  in  the  listing  file  is  vital  in 
debugging  because  it  provides  the  offsets  into  the  module  ^or  each 
program  section.  An  offset,  combined  with  the  base  load  address  for  a 
program  section  (from  the  Task  Builder  map) ,  allows  you  to  access 
locations  in  the  memory-resident  task  image  during  debugging. 


1.1.4  Task  Creation 

The  Task  Builder  (IKB)  on  RSX-llM  and  RSX-llM-PLUS  systems  is  a 
multiple-purpjse  tool.  It  allows  you  to  create  a  loadable  entity 
(called  a  ta ik  image)  ,  define  and  structure  a  shared  area  of  memory 
(called  a  resident  common)  ,  and  arrange;  shareable  routines  to  reside 
in  memory  (called  resident  libraries).  TKb  has  many  complex  aspects 
but  this  guide  introduces  only  its  moot  frequent  usage;  building  a 
task  image. 

DCL  users  Invoke  TKB  with  the  LINK  command.  MCR  users  invoke  the  TKB 
with  the  TKB  command. 

To  build  a  task  image,  TKB  accepts,  as  basic  input,  the  output  of  a 
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language  processor:  an  object  module  or  multiple  object  modules.  TKB 
can  optionally  generate  a  file  of  executable  code  (the  task  image) ,  a 
file  of  memory  allocation  information  (a  map) ,  and  a  special  file  of 
symbol  definitions  used  in  constructing  the  task  (the  symbol 
definition  file).  The  task  image,  residing  on  disk,  is  in  a  format 
suitable  to  be  loaded  into  memory  and  executed.  If  you  generate  a 
cross-reference  listing,  the  listing  itself  contains  only  global 
symbols  and  is  appended  to  the  map  file. 

In  creating  a  task  image,  TKB*s  primary  functions  are  linking,  address 
binding,  and  building  system  data  structures.  Linking  involves 
resolving  global  references  in  all  object  modules  and  resolving 
program  section  references  among  all  object  modules.  Address  binding 
is  assigning  virtual  address  space  within  the  task.  Building  system 
data  structures  involves  creating  elem<ants  that  the  system  requires  to 
load  the  task  image  into  memory  and  to  execute  the  task.  To  resolve 
glcbal  symbols  that  are  r^^  defined  in  any  of  the  input  object 
modules,  TKB  searches  any  ooject  libraries  you  specify  and,  as  a 
default  condition,  searches  the  system  object  library. 

Because  the  PDP-11  processor  can  address  only  32K  words  (the  address 
limit  of  16  bits)  at  any  one  time,  a  task  cannot  refer3nce  more  than 
32K  words  at  a  time.  However,  if  you  use  certain  advanced  programming 
techniques,  TKB  allows  a  task  to  access  more  code  or  data  than  can  fit 
within  the  address  limits.  Techniques  to  overcome  the  addressing 
limits  include  the  following: 

•  Overlaying  segments  of  a  task  with  either  disk-resident  or 
memory-resident  code 

•  Mapping  to  different  regions  of  memory  outside   the  physical 
limits  of  the  current  task  space 

Because  these  are  advanced  techniques,  they  are  not  shown  i  the 
examples  in  this  guide.  For  more  information  on  them,  refer  to  the 
RSX-llM/M-PLUS  Task  Builder  Manual. 

The  memory  allocation  information,  or  map,  produced  by  TKB  shows  you 
how  program  sections  are  arranged  in  task  memory  (the*r  starting 
virtual  addresses  and  extents  on  mapped  systems  and  physical  addresses 
and  extents  on  unmapped  systems) ,  what  contributions  are  in  a  program 
section,  any  undefined  symbols,  and  the  optional  cross-reference 
listing  of  global  symbols.  You  can  use  the  starting  virtual 
addresses,  combined  with  the  current  location  counter  values  (provided 
by  the  assembler) ,  as  offsets  to  access  locations  within  the 
memory-res5dent  task  during  debugging. 


1.1.    Debugging  Aids 

This  section  introduces  the  debugging  aids  described  in  this  guide  and 
provided  with  RSX-llM  and  RSX-llM-PLUS  systems  to  assist  in 
identifying  faulty  code. 


1.1.5.1  On-Line  Debugging  Tool  -  The  On-Line  Debugging  Tool  (ODT) 
allows  interactive  control  of  task  execution.  You  specify  to  TKB  that 
you  want  a  debugging  a'd  included  in  a  task.  TKB  inserts  into  the 
task  the  module  LB: [1, IJODT.OBJ. 

When  you  run  a  task  that  ip'.ludes  ODT,  execution  begins  at  the  ODT 
transfer  addross  rather  :.h^-  at  the  task  starting  address.  Therefore, 
ODT  gains  control  and  al i  <ws  you  to  type  special  commands  that 
establish  base  addresses  and  that  set  breakpoint  locations  within  the 
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task.  After  you  tell  ODT  to  bk>gin  task  execution,  ODT  saves  the 
instructions  at  breakpoint  locations  you  specified  and  replaces  then 
with  PDP-11  breakpoint  (BPT)  instructions.  Upon  encountering  a  BPT 
instruction  in  the  task,  the  Executive  passes  control  to  ODT  at  its 
breakpoint  routine.  ODT  saves  task  registers  in  special  locations, 
restores  instructions  to  the  breakpoint  locations,  and  transfers 
control  to  the  user  task  terminal.  By  typing  ODT  connands,  you  can 
examine  and  alter  any  instructions  or  data  within  task  memory. 

ODT  also  enables  the  BPT  synchronous  system  trap  (SST)  entry  point  in 
the  task.  If  a  task  generates  an  SST  error,  ODT  gains  control  at  its 
SST  entry  point,  prints  a  notice  at  the  user  terminal,  and  passes 
control  to  the  terminal.  You  can  use  the  ODT  co!i>mands  to  discover  the 
cause  of  the  error,  correct  it,  and  perhaps  continue  executing  the 
task. 

To  successfully  modify  instructions,  you  must  have  a  thorough 
understanding  of  the  PDP-11  instruction  set.  If  you  are  programming 
in  a  high-level  language,  you  should  avoid  interactive  debugging 
whenever  possible. 


1.1.5.2  Postaortem  Duap  -  Postmortem  Dump  (PMD)  is  an  installed  task 
that  is  directed  by  the  Executive  to  extract  run-time  related  data 
about  a  terminated  task,  format  it,  and  request  a  printed  listing. ^ 
Normally,  when  a  task  generates  a  synchronous  system  trap  (SST) ,  such 
as  that  caused  by  an  improper  reference  to  an  odd  address  or  a 
reference  to  a  nonexistent  memory  location,  the  Executive  tries  to 
transfer  control  to  an  SST  entry  point  defined  by  the  task.  If  the 
task  does  not  huve  an  SST  routine  defined  for  the  particular  type  of 
trap,  the  Executive  aborts  the  task. 

To  terminate  the  task,  the  Executive  performs  an  abort  operation  and 
notifies  the  Task  Termination  Notification  program  (TKTN) .  TKTN 
displays,  on  the  user  terminal,  the  reason  for  the  termination  and  the 
contents  of  the  task  registers. ^  Without  PMD,  you  can  acquire  no 
further  information  about  the  task.^ 

By  enabling  Poi  mortem  Dumps  for  a  task  that  itself  does  not  handle 
synchronous  system  traps,  you  tell  the  Executive  to  supply  more  data 
at  abnormal  task  termination.  That  is,  the  Executive  follows  the 
abort  procedure  and,  in  addition,  creates  a  request  for  PMD  to  create 
the  dump.  PMD  examines  system  and  task  structures  to  preserve  status 
and  run-time  data,  reads  the  task  image  from  memory,  and  writes  it  to 
disk  in  a  readable  format.  PMD  then  queues  a  request  to  print  the 
file  containing  the  duR.p  data,  after  which  the  Executive  completes  the 
task  abort  procedure. 


1.1.5.3   Snapshot  Dump  -  The  snapshot  dump  ($SNAP) ,   also   using   PMD, 
generates  an  edited  dump  of  a  running  task.   Because  the  snapshot  dump 


1.  PMD  requires  that  the  Executive  option  toi.  abnormal  task 
termination  and  device-not-reafly  messages  be  selected  at  sy.'item 
generation  time. 

2.  The  TKTN  task  must  be  installed  on  the  system  to  display  rhe 
messages. 

3.  Commands  exist  that  allow  you  to  fix  a  task  In  memory  and 
physically  examine  the  contents  of  the  task  image.  However,  this  is  a 
complicated  procedure  and  beyond  the  scope  of  this  book. 
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requires  you  to  insert  special  code  (for  example,  the  $SMAP  nacro 
call)  in  a  task,  it  is  nore  difficult  to  use  than  PMD.  However,  by 
inserting  the  snapshot  dump  code  in  the  task,  you  can  choose  the 
location  at  which  the  dump  is  created  and  select  the  extent  and  fornat 
of  the  dunp.  In  addition,  you  can  generate  the  dunp  fron  more  than 
one  location  and,  therefore,  as  many  times  as  needed  during  task 
execution. 

It  is  often  useful  to  include  debugging  facilities  such  as  $SNAP  in 
your  task  based  on  defining  a  conditional  variable.  To  Include  the 
facility  while  you  are  debugging,  simply  define  the  variable.  You  can 
then  omit  the  facility  by  reassembling  the  code  with  the  conditional 
variable  undefined. 


1.1.6  General  Utilities 

This  section  introduces  the  general-purpose  utility  programs  that  are 
mentioned  in  this  guide. 


1.1.6.1  Cross-Reference  Processor  -  The  Cross-Reference  Processor 
(CRF)  is  an  installed  task  that  receives  requests  from  MACRO-11  and 
TKB  to  generate  cross-reference  listings  of  symbols.  CRF  generates  a 
specially  formatted  file  containing  the  cross-reference  data  and 
appends  that  file  to  the  assembler  listing  or  the  task  map  file. 
Therefore,  if  you  request  a  cross-reference  listing  of  symbols,  it 
always  appears  at  the  end  of  a  listing  or  map  file. 

A  request  for  the  services  of  the  Cross-Reference  Processor  is 
included  in  your  command  line  to  the  NACRO-11  Assembler  and  TKB.  From 
DCL,  use  the  /CROSS_REFERENCE  qualifier  to  the  MACRO  and  LINK 
commands.  From  MCR,  use  the  /CR  switch  on  the  proper  file 
specification  in  the  MAC  and  TKB  command  lines. 


1.1.6.2  Peripheral  Interchange  Program  -  The  Peripheral  Interchange 
Program  (PIP)  is  the  standard  DIGITAL  program  for  performing  file  and 
device-related  functions:  transferring  files  from  one  medium  or  User 
File  Directory  (UFD)  to  another,  obtaining  directory  listings, 
renaming  files,  deleting  files,  and  changing  file  protection  codes. 
PIP  handles  all  Files-11  file-structured  devices  and  is  used  for 
almost  all  file  operations.  The  noteworthy  exception  to  PIP 
capabilities  is  certain  PDP-11  Record  Management  Services  (RMS-11) 
file  operations,  for  which  DIGITAL  supplies  special  RMS-11  utilities* 

MCR  users  access  PIP  services  through  various  PIP  commands.  DCL 
includes  the  DIRECTORY,  DELETE,  PURGE,  COPY,  RENAME,  TYPE,  APPEND,  and 
SET  PROTECTION  commands,  which  give  you  transparent  access  to  PIP 
s'irvices. 


1.1.6.3  Queuing  and  Spooling  -  RSX-llM  and  RSX-llM-PLUS  systems 
differ  in  the  manner  in  which  each  provides  queuing  and  spooling 
facilities,  but  both  systems  generally  offer  the  same  user  functions. 
Almost  all  program  development  tasks  automatically  generate  requests 
to  the  proper  queuing  tasks  to  print  an  ASCII  output  file  on  the 
system's  default  printer.  If  your  installation  has  the  proper  tasks 
installed,  the  spooling  task  dequeues  such  requests  and  prints  the 
requested  output  file  on  the  proper  device.  You  should  consult  the 
system  manacjer  at  your  installation  for  the  exact  details. 
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1.1.6.4  Librarian  Operat 
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DCL  includes  a  series  of  LIBRARY  commands  that  give  you  access  to   LBR 
services.   MCR  users  access  LBR  services  through  various  LBR  commands. 


1.2   DIGITAL-SUPPLIED  SYSTEM  SOFTWARE 

DIGITAL  supplies  system  software  in  two  standard  library  formats: 
macro  call  definitions  and  object  module  subroutines.  You  use  macro 
libraries  as  input  to  the  assembler  and  object  libraries  as  input  to 
TKB.   The  following  two  subsections  describe  these  system  libraries. 


1.2.1   Systen  Directives  -  Macro  Libraries 

DIGITAL  makes  available  system  directives  and  system-related  features 
through  calls;  definitions  for  these  calls  reside  in  macro  libraries. 
The  libraries  are  stored  in  a  predefined  file  area  known  as  a  User 
File  Directory  or  UFD.  The  UFD  is  [1,1]  on  the  system  library  device 
(referenced  explicitly  by  the  device-independent  designation  LB:). 
Table  1-1  summarizes  the  macro  libraries  that  DIGITAL  supplies. 


Table  1-1 
DIGITAL-Supplied  Macro  Libraries 


File  Name  and  Type 

Description  of  Contents 

RSXMAC.SML 

System  Macro   Library.    Contains   the   macro 

definitions   for  all  RSX-llM  and  RSX-llM-PLUS 

system  directives  and   File   Control   Service 

(FCS)  file-processing  calls.   Default  library 

for  the  assembler. 

EXEMC.MLB 

Executive  Macro  Library.   Contains  the  symbol 

and  offset  definitions  for  the  Executive  data 

structures. 

RMSMAC.MLB 

PDP-11  Record   Management   Services   (RMS-11) 

Library.   Contains  the  definitions  for  RMS-11 

calls  for  sequential  and  relative   file   I/O. 

If   your   system   has   the   optional   RMS-llK 

software,   this   library  will   also   contain 

calls  for  indexed  file  operations. 

1.  The  Librarian  can  also  create  a  universal  library  file   to 
any  of  one  file  type  you  prefer. 


contain 
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To  us*  th«a*  llbrari**,  you  should  follow  tho  specific  procoduros 
d*scrib«d  in  th«  systsa  docuaontation.  Typically,  you  supply  in  tha 
sourca  coda  tha  appropriata  namas  of  tha  nodulas  aa  paranetars  of  a 
.NCALL  NACRO-11  diractiva.  This  action  tails  tha  assanblar  to 
ganarata  an  antry  for  that  call  in  its  nacro  symbol  tabla  and  to 
saarch  tha  appropriata  library  for  tha  dafinltion  of  tha  nacro  aymbol. 

In  translating  sourca  coda,  tha  assaabl«»r  first  chacka  for  nacro 
syabols.  Whan  tha  assaablar  finds  an  oparator  on  a  sourca  lina,  it 
saarchas  its  nacro  synbol  tabla  to  sea  whether  tha  operator  is  a  nacro 
synbol.  An  operator  is  any  PDP-11  operation  coda,  NACRO-11  Assanbler 
directive,  or  nacro  synbol.  If  the  operator  is  a  nacro  synbol,  tha 
assanbler  applies  the  local  definition  for  the  nacro  synbol  or 
extracts  the  definition  fron  a  library  you  specified  or  fron  the 
systen  library.  By  searching  the  user-supplied  library  first,  the 
assanbler  allows  you  to  tailor  the  definitions  of  systen  nacro  calls 
or  PDP-11  instructions.  NACRO-11  assenbles  the  macro  definition  with 
any  acconpanying  paraneters  and  includes  the  assenbled  code  in  the 
object  nodule.  As  a  reault,  the  proper  code  is  included  fron  a 
library. 

Through  the  use  of  the  systen  nacro  library,  you  are  provided  with  the 
code  that  enables  a  task  to  issue  systen  directives  and  to  ob'.ain  the 
Pile  Control  Services  (PCS).  These  services  enable  a  task  to  obtain 
run-tine  and  systen  infornation,  perforn  input/output  functions, 
connunicate  with  other  t.iisks,  nanipulata  logical  and  virtual  address 
space,  control  execution,  and  properly  exit.  In  general,  nost  RSX-llN 
and  RSX-1 IN-PLUS  features  are  nade  available  to  a  task  through  nacro 
calls  to  the  systen  nacro  library.  Por  the  system  macro  library 
RSXNAC,  you  need  not  designate  the  library  nana  to  the  assembler.  As 
a  default  condition,  the  assembler  automatically  searches  the  systen 
nacro  library. 

Through  the  use  of  the  Executive  nacro  library  EXENC.NLB,  you  are 
provided  with  code  to  allow  software  to  refer  to  offsets  within  the 
Executive  and  system  definitions  of  the  Executive  data  structures. 
This  library  is  provided  for  assembling  privileged  tasks  and  for 
incorporating  specially  written  device  drivers  into  the  systen.  (This 
topic  is  covered  fully  in  the  RSX-1 IN-PLUS  Guide  to  Writing  an  I/O 
Driver,  the  RSX-llN  Guide  to  Writing  aira"  I/O  oTTver,  and  the 
ksx-llN/N-PLUS  Task  Builder  Nanual ,  and  Ts  not  mentioned  further  in 
this  guide.) 

The  Record  Nanagement  Services  library  RNSNAC.NLB  is  provided  to 
support  file  and  record  access  to  RNS-11  data.  RNS-11  is  an 
upwards-compatible  extension  of  PCS  and  offers  more  functions  such  as 
indexed  sequential  (keyed)  access  to  data.  You  include  the  RNS-11 
macro  symbols  in  the  source  code  and  supply  to  the  assembler  the  name 
of  the  RNS-11  library  to  use.  The  assembler  extracts  the  definitions 
from  the  library  and  includes  the  RNS-11  code  in  the  object  module. 


1.2.2  Systen  Subroutines  -  Object  Libraries 

On  RSX-llN  and  RSX-llN-PLUS  systems,  system  object  libraries  provide 
general  utility  functions  and  special-purpose  Executive  features. 
These  libraries,  like  the  macro  libraries,  reside  in  UPD  [1,1]  on  the 
system  library  device  (LB;).  Table  1-2  lists  and  describes  the  object 
libraries  that  DIGITAL  supplies. 
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Table  1-2 
DIGITAL-Supplled  Object  Libraries 


Pile  Name  and  Type 


SYSLIB.OLB 


VMLIB.OLB 


EXELIB.OLB 


AMSLIB.OLB 


RMSLIB.OLB 


FOROTS.OLB 
F4P0TS.0LB 


Description  of  Contents 


System  Library.  Contains  register  handling, 
arithmetic,  data  conversion,  output 
srmatting.  Pile  Control  Services  (PCS),  and 
PCS  command  line  processing  subroutines. 
Optionally  contains  a  set  of  real-tiuie  data 
acquisition  routines.  Default  library  for 
TKB. 

Virtual  Memcry  Management  Library.  Contains 
dynamic  memory,  core  allocation,  virtual 
memory,  and  page  management  subroutines. 

Executive  Library.  Contains  the  definitions 
of  the  Executive  symbols. 

ANSI  Magnetic  Tape  Library.  On  RSX-llM 
systems  only,  an  alternate  version  of 
SYSLIB.  Contains  ANSI  magnetic  tape  label 
handling  routines  and  PCS  big  buffering 
support.  (On  RSX-llM-PLUS  systems  and 
systems  with  limited  disk  space,  these 
routines  are  In  SYSLIB.) 

Record    Management  Services    Library. 

Contains  the  routines  for  sequential  and 

relative  (RMS-11)  and,  optionally,  Indexed 
(RMS-llK)  I/O. 

FORTRAN  IV  and  PORTRAN  IV-PLUS  Library 
(optional) .  The  Object  Time  System  (OTS) 
and  other  routines  for  the  PDP-11  PORTRAN  IV 
language  processors. 


You  typically  Include  system  object  routines  in  a  task  by  specifying 
the  routine  name  as  the  operand  of  a  CALL  macro  or  Jump  To  Subroutine 
(JSR)  Instruction  in  the  source  code.  The  language  processor,  at  the 
point  of  the  reference,  generates  the  instructions  to  transfer  control 
to  the  external  subroutine.  The  name  of  the  subroutine  is  left  as  an 
externally-defined  global  symbol  for  TKB  to  resolve. 

To  ensure  that  subroutines  are  placed  in  the  task  image,  TKB,  as  a 
default  operation,  searches  the  library  SYSLIB.OLB  for  routine  names 
that  remain  undefined  after  the  search  of  any  user-specified 
libraries.  TKB  attempts  to  match  the  undefined  global  reference  (the 
subroutine  name  in  ?  module)  with  an  entry  point  name  in  the  SYSLIB 
library.  When  it  finds  a  match,  TKB  extracts  a  copy  of  the  module 
defining  the  symbol  from  SYSLIB  and  Inserts  the  subroutine  in  the  task 
image.  Any  further  references  to  that  symbol  in  the  task  are  defined 
by  the  subroutine,  and  TKB  need  not  add  any  code  to  resolve  further 
references. 

If  a  module  references  routines  that  are  in  an  object  library  other 
than  SYSLIB.OLB,  you  must  specify  that  library  when  you  build  the 
task.  TKB  performs  the  same  search  operations  on  user-supplied 
libraries  as  it  does  on  the  default  search  of  SYSLIB.  TKB  also 
searches  any  user-specified  libraries  in  the  order  in  which  you 
specify  them  before  it  searches  the  system  library. 
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1.3   HAROMARE  FOR  PROGRAM  DEVELOPMENT 

Basically,  you  need  three  types  of  devices  for  progran  developaent: 
disks,  terminals,  and  printers.  This  section  briefly  introduces  these 
devices  and  tells  where  you  can  find  further  infornation.  In  general, 
each  hardware  unit  on  the  system  is  delivered  with  relevant  hardware 
documentation  that  provides  programming  information  in  addition  to 
operational  ir.scructions.  Your  installation  should  have  a  library  of 
such  hardware  documentation.  If  you  are  not  writing  any  specially 
tailored  code  for  these  devices,  the  system  software  handles  them 
transparently  through  such  mechanisms  as  the  print  spooler  and  PIP. 


1.3.1  Disks 

Disks  are  the  main  storage  media  on  RSX-llM  and  RSX-llM-PLUS  systems. 
Disk  drives  are  either  public  (that  is,  accessible  to  all  users)  or 
private  (that  is,  accessible  to  a  restricted  set  of  users).  Almost 
all  utility  programs  work  with  disks  as  their  default  device.  You  can 
share  public  disk  resources  to  create  source  program  files  and,  as 
needed,  allocate  your  own  private  drive  to  store  reserved  copies  of 
source  and  documentation  files. 


1.3.2  Terminals 

Terminals  are  the  means  by  which  you  communicate  with  the  system. 
DIGITAL  terminals  handle  7-bit  ASCII  characters  and  system  software 
usually  ignores  any  eighth,  or  parity,  bit.  You  perform  input  to  the 
system  through  a  typewriter-like  keyboard;  the  system  returns  output 
to  you  either  on  a  screen  at  a  video-display  terminal  or  on  paper  at  a 
hard-copy  terminal.  Video-display  terminals  are  more  convenient 
because  they  typically  operate  at  faster  rates  than  hard-copy  devices. 
Hard-copy  terminals,  however,  have  the  advantage  of  providing  a  record 
of  what  transpired  during  a  session  on  the  system. 

Terminals  are  connected  to  the  computer  through  either  a  direct  line 
or  a  modem  unit  over  a  dial-up  telephone  l!ne.  If  you  are  not 
familiar  with  using  a  terminal,  you  should  read  the  Introduction  to 
RSX-llM  and  RSX-llM-PLUS  and  the  RSX-llM/M-PLUS  Command  Language 
Manual ."  These  manuals  explain  how  to  ^  access  the  system  and  basic 
system  functions  using  DCL.  The  RSX-llM/M-PLUS  MCR  Operations  Manual 
explains  how  to  access  the  system  and  basic  system  functions  using 
MCR. 


1.  .3  Printers 

Printers  provide  hard-copy  output  of  data.  On  larger  systems,  you 
communicate  with  the  printer  through  the  Queue  Manager  subsystem. 
(See  the  RSX-llM/M-PLUS  Batch  and  Queue  Operations  Manual  for  more 
information  on  the  Queue  Manager.)  MCR  provides  a  PRI  command  and  DCL 
a  PRINT  command  on  systems  with  the  Queue  Manager.  On  smaller 
systems,  you  may  have  to  specify  explicitly  that  output  is  to  go  to  a 
line  printer.  All  systems  have  a  terminal  or  other  output  device 
serving  as  a  line  printer.  All  listings  from  the  MACRO-11  Assembler 
or  TKB  are  queued  to  the  system  line  printer. 
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1.4   THE  PROGRAM  DEVELOPMENT  PROCESS  -  OVERVIEW 

Figure  1-1  illustrates  the  steps  in  the  program  development  nrocess. 
The  following  paragraphs  briefly  describe  these  steps,  which  are 
treated  in  greate.  detail  in  Chapters  2  through  7. 
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Figure  1-1  The  Program  Development  Process 

The  steps  normally  taken  to  prepare  a  program  to  run  on  the  system  are 
as  follows: 

1.  Creat*>:  a  source  program  in  a  file  on  disk. 

2.  Submit  the  source  file  to  a  language  processor  (assembler  or 
compiler)  to  produce  an  object  module. 

3.  Submit  the  file  (or  files)  containing  the  object  or  nodules 
to  TKB  to  create  a  file  containing  a  loadable  task  image. 

4.  Request  the  Executive  to  execute  the  task. 

You  use  a  text  editor   to  create   the   source   file.    For  MACRO-11 

programmers,   this  guice  suggests  a  skeleton  format  for  source  files 

and  shows  how  to  replicate  and  modify  the  skeleton  file.   The  skeleton 

file  becomes  a  common  base  from  which  you  create  each  new  source  file. 
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A  lanquaq*  processor  cr«at«s  th«  filo  of  rolocatabl*  object  cod*.  For 
•ssMibly  language  procasalng,  HACRO-11  also  accassas  the  syataa  macro 
library  to  includa  coda  for  systaa  diractivas  In  tha  object  file.  For 
coapilers,  systea  directives  are  invoked  by  calls  to  subroutines  in 
the  system  object  library  SY8LIB. 

TKB  creates  the  file  of  loadable  code,  assuaing  certain  default 
conditions  about  the  run-tiae  environaent  and  building  these 
characteristics  into  the  task.  TKB  ulso  accesses  systea  and 
user-specified  libraries  to  resolve  references  in  the  task. 

Once  you  have  a  task  iaage,  you  request  the  Executive  to  run  the 
prograa.  If  any  errors  are  encountered,  you  aust  edit  the  source 
file,  reasseable  or  recoapile,  build  a  new  task  iaage  file,  and  try 
again. 


1.5  GUIDE  TO  FURTHER  READING 

The  sections  or  chapters  in  the  following  docuaents  contain  additional 
inforaation  on  the  subjects  described  in  this  chapter. 

Docuaent 

Introduction  to  RSX-llM  and  R8X-11M-PLUS 

RSX-llM/M-PLUS  Coaaand  Language  Manual 

Chapter  1,  Introduction 
Chapter  3,  Terainal  Operations 
Chapter  4,  Handling  Files 
Chapter  6,  Prograa  Developaent 

RSX-llM/M-PLUS  WCR  Operations  Manual 

Chapter  1,  Introduction  to  MCR 
Chapter  2,  Systea  Conventions 

RSX-llM/M-PLUS  Utilities  Manual 

Chapter  1,  Introduction 
EDT  Editor  Manual 

Chapter  1,  Introduction  to  EDT 
RM8-11  user's  Guide 
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CHAPTER  2 
CRBATIMG  MACRO-11  SOUKCB  riLBS 


Your  first  step  In  prooran  d«v«lopaicnt  is  to  crsat*  a  fil*  that 
contains  NACRO-11  sout  f  stataaents.  One  t/ay  to  do  this  is  to  ciaata 
a  skeleton  source  file  that  you  can  use  aa  a  franework  for  all  your 
source  prograas.  This  chapter  describes  a  source  fil«  foraat  that  you 
can  use  as  a  guideline  to  create  youi.'  owr.  8k4leton  file,  presents  soaie 
NACRO-11  statenents  to  include  in  Mh*  file,  and  explains  soae 
elementary  editing  connands  that  you  can  use  to  create  and  modify 
source  files. 

DIGITAL  has  established  a  coding  standard  to  enhance  the  readability 
and  maintainability  of  its  MACRO-11  source  programs.  That  standard  is 
outlined  in  an  appendix  of  the  PpP-11  MACRO-11  Language  Reference 
Manual,  the  reference  for  iWicR  T*  given  Tn  the  list  of  further 
read inn  at  the  end  of  this  chapter 


2.1   M;ACR0-11  SKELETON  SOURCE  PILE  POWIAT 

This  section  presents  the  skeleton  and  source  statement  formats  and 
discusses  each  of  the  elements  in  the  skeleton.  Figure  2-1 
illustrates  the  basic  elements  of  the  skeleton:  a  preface, 
definitions,  functional  descriptions,  and  the  code  itself. 

The  source  file  preface,  or  preamble,  should  be  on  the  first  page. 
The  preface  essentially  describes  the  code,  states  its  ownership, 
identifies  the  author,  defines  the  changes  to  the  code,  and  gives  a 
brief  description  of  the  module's  function. 

After  the  preface  of  the  module  comes  the  detail  of  the  code. 
Declarations,  such  as  local  symbol,  macro,  and  data  definitions, 
appearing  toward  the  front  of  the  code,  make  reading  the  code  easier. 
Preceding  the  routines  in  the  module  you  should  place  detailed 
descriptions  of  tfhat  the  routines  do,  and  define  trhat  is  required  for 
input  to  the  routines,  %rhat  the  routines  produce,  and  what  effects 
result  from  execution. 

Bach  statement  line  in  a  source  file  should  follow  a  consistent 
format,  as  shown  in  Figure  2-2. 
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CRSATIKG  MACRO-ll  SOORCe  FILES 
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Figure  2-1  MACRO-11  Source  Fll«  Foraat 
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Figure  2-2   NACRO-11  Source  Statement  Poriaat 


Although  the  assenbler  allows  free  formatting  of  atatenents,  you 
should  follow  the  reconmended  format  because  it  is  easy  to  follow  and 
creates  readablu,  consistent  code. 

In  the  source  statement  format  shown  in  Figure  2-2,  the  label  is  any 
I'^ar-def ined  symbol  that  identifies  a  Reference  location  in  the  code. 
An  operator  is  any  PDP-11  operation  code,  MACRO-11  Assembler 
directive,  or  macro  symbol.  An  operand  is  any  argument (s)  or 
parameter (s)  of  an  operator.  Comments  consist  of  information  you 
provide  to  describe  what  effect  you  desire  from  the  execution  of  the 
instruction.  Comments  do  not  affect  program  execution;  the  assembler 
merely  transfers  them  to  the  listing  file  produced  during  the 
assembly. 

Comments,  accompanied  by  selected  HACRO-11  Assembler  directives, 
constitute  the  source  file  skeleton.  This  skeleton  provides  the 
structure  on  which  you  build  the  source  file.  Directives  in  the 
source  file  skeleton  identify  the  code  and  control  the  format  of  the 
listing.   Example  2-1  shows  a  sample  skeleton. 


Sections  2.1.1  through  2.1.12  describe  the  parts  of 
skeleton  in  detail. 


the   source   file 


2.1.1   .TITLE  Directive 

The  .TITLE  directive  allows  you  to  name  the  module.  The  assembler 
takes  the  first  six  nonblank  characters,  up  to  the  first  blank  or 
horizontal  tab  character,  as  the  module  name.  Following  the  name  in 
the  .TITLE  directive,  you  can  use  up  to  24  characters  to  describe 
generally  the  function  of  the  module.  The  name  and  the  description 
appear  as  the  first  entry  in  the  header  line  of  each  page  in  the 
assembly  listing.  For  example,  consider  the  following  .TITLE 
directive; 

.TITLE  SKELTN  SOURCE  FILE  SKELETON 

The  assembler  takes  the  characters  SKELTN  as  the  module  name.  The 
remaining  characters  up  to  the  30th  character  are  taken  as  the 
description.  Any  remaining  characters  after  the  30th  character  would 
be  discarded. 

The  assembler  does  not  relate  the  name  you  specify  in  the  .TITLE 
directive  to  the  name  you  specify  for  the  source  or  object  files.  To 
minimize  confusion,  however,  it  is  helpful  to  apply  the  name  specified 
in  the  .TITLE  directive  to  the  source  file.  (Note  that  the  sample 
code  and  commands  shown  in  this  guide  use  different  names  to  help  you 
distinguish  their  usages.) 
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Bxaapl*  2-1   Saanl*  Sourc*  Pll*  Sk«laton 


.TITLE   8KELTN   80UKCC   FILE     SKELETON 
.lOCNT   /Ol/ 


AUTNOItt  Z 


changes; 


NODULE  FUNCTION! 


*PA8E  »  SREAK  PABE  FOR  PREFACE 

.8BTTL  SYNtOLt  NACROf  DATA  DEFINITIONS 

.LIST  TTH 

.NLIST  BEX  ISUPPRES8  DIN  EXTENSION 

.HCALL  EXITtS  I EXEC '8  EXIT  NACRO 


LOCAL  8YND0L  DEFINITIONS! 


LOCAL  NACROSt 

LOCAL  DATA  BLOCKS! 

.P8ECT   DATAiDfRU 

FUNCTION  DETAILS! 

INPUTS! 
OUTPUTS! 

SIDE  EFFECTS! 

■■ 

»  START  CODE  HERE 

.PAGE 

.S8TTL 

.PSECT 


START! 
END! 


EXIT$S 
.END 


lEXIT  CLEANLY  TO  EXEC 
tTELL  ASSEMBLER  END  OF  CODE 


a^ 


# 
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Horaover,  the  naa*  th«  assembler  sxtracts  froM  th*  .TITLE  dlractiv*  is 
iaportant  in  subsequent  steps  of  progran  developnent.  The  Task 
Builder  (TKB)  lists  this  name  in  its  nenory  allocation  synopsis  to 
show  which  object  modules  nade  contributions  to  each  progran  section 
in  the  task  iaage.  In  addition,  if  the  object  nodule  is  inserted  in 
an  object  library,  the  Librarian  Utility  Progran  (LBR)  keeps  this  nana 
in  the  directory  of  the  library  to  refer  to  the  object  nodule. 


2.1.2   .IDBMT  Directive 

The  .IDENT  directive  records  the  version  of  the  nodule.  Ycu  can 
establish  your  own  version  identification  conventions.  The 
identification  follo%fS  the  nodule  into  the  task  inage  &nd  is  displayed 
in  the  nap.  Knowing  %fhether  the  correct  version  of  the  nodule  was 
linked  into  the  task  inage  helps  in  the  debugging  and  naintenance 
process. 


2.1.3  Author  Line 

The  author  line  identifies  the  originator  of  the  code. 

2.1.4  Changes  Section 

This  section  of  the  source  file  describes  any  nodif ications  that  have 
been  nade  to  the  nodule.  You  can  develop  a  convention  tfhereby  the 
author's  initials  and  a  number  can  tag  a  change.  The  author  of  the 
change  can  identify  the  change  in  this  section  and  flag  each  line  of 
code  with  an  additional  connent,  such  as  the  following! 

I  TOM  JONES      8-AUG-81        ;TJ001 
;        ADD  STATE  TAX  TO  TOTAL 

Then,  in  the  code  a  changed  or  added  line  can  be  flagged  with  the 
notation  TJOOl. 

ADD    A,B  iTOTAL  WITH  TAX   ;TJ001 

This  procedure  helps  the  author  recall  what  changes  were  nade  to  the 
nodule  and  assists  others  in  deternining  the  extent  of  changes.^ 


2.1.5  Nodule  Function 

In  the  nodule  function  part  of  the  source  file,  you  can  describe  the 
general  processing  operations  that  the  code  perforns.  This 
description  can  include  how  the  nodule  relates  to  the  systen  or 
specific  application,  that  is,  «rhat  type  of  processing  precedes  and 
follows  the  execution  of  this  nodule. 


1.  A  utility  called  the  Source  Language  Input  Progran  (SLP)  is 
supplied  with  the  systen  and  can  be  used  for  source  file  naintenance. 
SLP  provides  the  neans  to  update  lines  in  an  existing  source  file  and 
to  apply  an  audit  trail  to  identify  lines  deleted,  replaced,  and 
added.  NCR  users  access  SLP  through  various  SLP  conmands.  DCL  users 
access  SLP  through  the  EDIT/SLP  connand. 
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2.1.6  Soaa  Us*ful  Directives 

Between  the  module  function  description  and  the  local  syabol 
definitions  is  a  convenient  place  to  insert  some  general-purpose 
directives.  The  following  subsections  describe  these  directives. 


2.1.6.1  .PAGE  Directive  -  The  .PAGE  directive  causes  a  page  break  in 
the  assembly  listing.  It  appears  as  shown  in  Figure  2-3  to  k-sep  the 
preamble  alone  on  the  first  page  of  the  listing  (after  the  table  of 
contents) .  You  can  use  the  .PAGE  directive  throughout  the  module  to 
generate  page  breaks  for  different  subroutines. 


2.1.6.2  .SBTTL  Directive  -  The  .SBTTL  directive  creates  an  entry  for 
the  assembly  listing  table  of  cont  nts  printed  at  the  front  of  the 
listing.  A  table  of  contents  is  helpful  in  summarizing  the 
subroutines  in  a  large  module.  Therefore,  the  text  you  supply  with 
the  directive  ought  to  describe  what  the  related  subroutine  does.  In 
addition  to  appealing  in  the  table  of  contents,  the  text  appears  on 
the  second  line  of  the  heading  at  the  top  of  each  listing  page.  If 
your  modules  typically  contain  only  a  small  number  of  subroutines,  you 
probably  will  not  find  the  table  of  contents  feature  very  useful. 


9..  1.6. 3  .LIST  TTM  Directive  -  The  .LIST  TTM  directive  creates  a 
listing  formatted  more  conveniently  for  ouput  on  a  terminal.  (Section 
3.4  of  this  guide  shows  how  to  display  a  listing  at  a  terminal.)  The 
directive  can  be  included  during  the  early  stages  of  program 
development  and  removed  from  the  stabilized  code. 


2.1.6.4  .NLIST  BEX  Directive  -  The  .NLIST  BEX  directive  suppresses 
the  binary  extension  jf  statements  beyond  what  can  fit  on  one  source 
statement  line.  Using  this  directive  saves  much  excess  printing  in 
the  assembly  listing.  For  example,  only  the  binary  value  of  the  first 
three  characters  of  an  ASCII  string  would  appear  in  the  listing.  The 
directive  simply  makes  the  listing  iiore  readable  and  saves  paper. 


2.1.6.5  .MCALL  Directive  -  The  .MCALL  directive  is  the  means  by  which 
you  tell  the  ctssembler  the  names  of  the  externally  defined  macro  calls 
that  appear  in  the  source  file.  The  directive  causes  the  assembler  to 
create  entries  in  its  macro  symbol  table  for  the  macro  names  and  to 
look  up  the  definitions  of  the  related  calls  in  either  a  user  or  a 
system  macro  library.  The  assembler  includes  the  definitions  from  the 
library  in  the  module  where  the  calls  themselves  appear. ^ 


1.  If  you  do  not  include  the  directive  .LIST  ME  (list  macro 
expansions)  or  .r.IST  MEB  (list  macro  expansion  lines  that  generate 
object  code)  in  th>  source  file,  the  assembler  does  not  insert  in  the 
listing  the  expanded  source  code  of  the  macros  it  assembles. 
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Th«  BXITSS  dir*ctiv«  (shown  In  th«  .NCALL  statenent)  should  b«  In 
•very  U8«r  prograa  for  a  claan  axit.  It  is  the  last  statanant  tha 
program  (task)  axacutas  bafora  it  raturns  control  to  tha  Exacutiva. 
(Tha  BXIT98  diractiva  performs  important  systan  housakaaplng 
oparations  for  tha  task.)  Tha  ralatad  definition  for  BXIT$8  rasidas  in 
tha  fila  RSXMAC.SML  in  UPD  [1,1]  on  tha  library  davica  (LBt).  DIGITAL 
racoaaands  that  usar  tasks  axit  by  using  tha  EXIT$S  diractiva.  (An 
altarnativa  fora  of  axiting  allows  a  task  to  axit  and  post  status.) 

If  a  call  for  an  axtarnally  defined  aacro  stataaant  appears  in  tha 
source  fila  but  is  not  preceded  by  an  .MCALL  directive  and  the  aacro 
naae,  the  asseabler  treats  the  unrecognised  aacro  call  as  an  iaplicit 
.WORD  data  storage  directive.  (If  the  aacro  call  has  paraaeters,  the 
asseabler  aay  generate  an  error  because  of  illegal  syntax  for  a  .WORD 
directive.)  Later,  when  you  build  the  task  with  the  related  object 
Bodule  and  the  aacro  naae  is  not  a  valid  syabol,  TKB  flags  the  naae  as 
an  undefined  reference.  Thus,  without  the  .MCALL  directive,  the 
asseabler  does  not  know  that  it  aust  search  libraries  to  resolve  the 
aacro  syabol. 


2.1.6.6  .END  Directive  -  The  .END  directive  in  a  aodule  signals  the 
logical  end  of  source  input  and  optionally  specifies  the  task  transfer 
address.  The  transfer  address  is  the  location  at  ifhich  prograa 
execution  begins.  Although  each  source  file  should  contain  an  .END 
directive,  only  one  source  file  should  define  the  transfer  address. 
Tha  asseabler  does  not  process  lin«-  beyond  the  one  on  which  the  .END 
directive  appears. 


2.1.7   Local  Definitions 

In  th's  section  of  your  source  file,  you  collect  symbols  in  direct 
assignaent  stateaents.  Because  symbols  in  MACRO-11  can  be  defined  as 
expressions  of  other  symbols,  having  the  definitions  in  one  place  is 
an  advantage.  In  addition,  good  programming  practice  encourages  using 
symbols  instead  of  simply  supplying  a  numeric  constant. 

For  example,  in  defining  a  10-byte  buffer,  the  best  method  is  to 
define  a  symbol  and  then  use  the  symbol  in  the  buffer  definition. 

I 

;  LOCAL  DEPIN'^^'IOMS 

; 

SIZB  >  10. 


; 

}  LOCAL  DATA  BLOCKS 

; 

BUPB:    .BLKB     SIZB 

This  method  has  several  advantag')8: 

•  I"  a  single  constant  that  is  referred  to  in  numerous  places  in 
the  code  must  be  altered,  you  need  perform  only  one  edit  (to 
thr:  syabol  definition}  to  eff«ct  the  chang4. 

•  If  all  the  symbols  are  gathered  in  one  place  in  alphabetical 
order,  reading  the  code  is  siaplified. 


2-7 


CRBATXSRS  SUCRO-ii  SOUKCS  rlLK 


You  can  find  all  rafaraneaa  to  a  ayabol  in  a  croaa-rafaranca 
liatinq.  Tha  croaa-rafaranca  capability  allowa  you  to  axaaina 
all  tha  rafarancaa  to  a  ayabol  and  confidantly  aaaaaa  tha 
affacta  of  altarinq  tha  ayabol  dafinition. 


rw 


if  you  uaa  conatanta. 


Thua,  tha  ayabol  liat  tiould  contain  auch  local  ayabol  dafinitiona  aa 
8IZB  -  10.  Tha  ayabola  thaaaalvaa  would  appaar  in  tha  aodula  coda. 


2.1.8  Local  Macro  Dafinitiona 

Tha  dafinition  of  a  macro  atataaant  can  appaar  anywhara  in  tha  aourca 
fila  aa  long  aa  tha  dafinition  appaara  bafora  tha  f^.rat  oecurranca  of 
tha  aacro  atataaant.  It  ia  battar  prograaaing  practica,  than,  to 
placa  all  aacro  dafinitiona  in  a  atandard  pl«.ca  naar  tha  front  of  tha 
aourca  fila. 


2.1.9  Lo?al  t>sf   BlockA 

Thia  aaction  of  tho  sourca  fila  dafinca  auch  data  as  buffara,  ata4.ua 
•foida,  and  atatua  bytaa.  Ganarally,  it  <faa«:rit>«8  tha  local  atoraga 
that  tha  aodula  rafarancaa.  It  ia  good  prograaaing  praccica  to  uaa  a 
aaparata  .PSftCT  dircctiva  for  data.  Saa  Saction  2.1.11. 


2.1.10  Nodula  Function  -  Datailad 

Thka  aaction  of  tha  aourca  fila  can  ba  aa  ganaral  or  apacific  aa 
naadad  to  daacriba  tha  functiona  of  tha  aodula.  A  coaplax  aodula 
ahould  hava  a  langthy  diacuaaion;  a  aiapla  aodula  naad  not  hava  aa 
auch.  At  a  ainiaua,  thia  aaction  ahould  atata  tha  ragiatar  uaaga  on 
input  to  and  output  froa  tha  aodula. 


2.1.11   .P8ICT  Diractiva 

Tha  .P8BCT  diractiva  aatabliahaa  a  naaa  and  attributaa  for  a  prograa 
aaction.  A  prograa  aaction  ia  a  unit  allocation  of  aaaory  raaarvad 
for  aithar  coda  or  data.  For  axaapla,  you  can  astabliah  a  prograa 
aaction  to  contain  data  for  your  prograa  aa  followat 

.PSBCT  DATA,D,RW 

Tha  . PSBCT  diractiva  craataa  tha  prograa  aaction  naaad  DATA  with  tha 
attributaa  data  (D)  and  raad/writa  (RW) .  You  aay  giva  a  prograa 
aaction  for  data  aithar  tha  raad-only  (RO)  or  tha  raad/writa  (RW) 
attributa.  (Tha  aaaaablar  appliaa  othar  dafault  attributaa  not 
ralavant  to  thia  diacuaaion.) 

R8X-11M  ayataaa  do  not  aupport  hardwara  protaction  of  prograa  aactiona 
that  hava  tha  RO  attributa. 

R8X-11M-PLU8  ayataaa  aupport  hardwara  protaction  of  prograa  aactiona 
that  hava  tha  RO  attributa  if  thay  ara  in  tha  pura  coda  of  a  aultiuaar 
taak. 
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Consult  th«  RSX-llM/M-PLUS  Task  BulldT  Manual  for  a  discussion  of 
prograa  sactlon  allocation  in  aultiusor  tasks. 

Th«  thras  aost  iaportant  aspacts  of  tha  .P8BCT  diractiva  arat 

a  Contributions  dafinad  for  a  spacific  program  saction  can  ba  in 
saparata  placas  in  a  sourca  fila  or  in  saparata  sourca  filas. 

a  Ttia  attributas  of  tha  program  saction  ara  passad  to  TKB. 

a  Contributions  for  a  spacific  program  saction  with  tha  sama 
attributaa  ara  collactad  in  ona  continuous  allocation  of 
aaaory  spaca  by  TKB. 

In  tha  skalaton  fila,  it  is  usaful  to  dafina  ona  progrom  saction  to 
contain  tha  data  alamants  rafarancad  in  tha  task  and  to  dafina  anothar 
program  saction  to  contain  tha  code. 


2.2   CRBATIMG  A  SOURCE  FILE  PROM  A  8RBLBT0M  PILE 

This  saction  dascribas  how  to  use  an  aditor,  EDI,  to  create  a  skeleton 
file  and  then  to  create  a  source  file  from  the  skeleton.  If  you  are 
using  EOT  or  some  other  editor,  follow  the  text  for  EDI  and  perform 
the  functions  using  your  editor. 


2.2.1  Performing  tha  Initial  Input 

To  create  the  skeleton  file  using  MCR,  type  EDI  and  the  specification 
of  a  new  file,  that  is,  one  that  is  not  in  your  directory.  For  DCL, 
use  the  command  EDIT/EDI  and  the  specification  of  a  new  file. 

Hare  is  the  sequence  from  a  DCL  terminal: 

DCL>EDIT/EDI  SKEL.MAC 
(CREATING  NEW  FILE] 
INPUT 

Hare  is  the  sequence  from  an  MCR  terminal: 

MCR>EDI  SKEL.MAC 
[CREATING  NEW  FILE] 
INPUT 

The  editor  runs,  determines  that  the  file  does  not  exist,  creates  the 
file,  and  tells  you  to  begin  typing  the  input. 

Type  the  input  according  to  Example  2-2.  Leave  any  typographical 
errors  until  after  you  have  become  familiar  with  the  editing  commands 
described  in  Section  2.3.  The  notation  conventions  appearing  in  the 
figure  are  described  in  the  Preface  at  the  front  of  this  guide. 


2.2.1.1  Inserting  Blank  Lines  in  Test  -  To  insert  a  blank  line  in  the 
source  file  as  shown  in  Example  2-2,  type  a  space  or  tab  on  a  new  line 
followed  by  the  RETURN  key.  If  you  type  the  RETURN  key  twice  in 
succession  (that  is,  type  the  RETURN  key  to  enter  a  line  of  text  and 
immediately  type  the  RETURN  key  again  on  the  new  line),  EDI  terminates 
the  input.  Thus,  to  enter  a  blank  line,  you  need  type  only  one 
nonprint'ng  character,  such  as  TAB,  on  a  new  line. 


a*»t 
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2.2.1.2  Tarailnatinf  th«  Input  and  th«  IDI  Pregraa  -  To  t«ralnat«  tha 
input,  typa  tha  RBTURM  kay  twica  in  auccaoalon.  KDI  printa  tha 
aatariak  to  raquaat  a  coaaand.  Typa  tha  BXIT  cowaand  to  cloaa  tha 
fila  and  tarainata  BDI.   For  axaaplat 

last  lina  of  taxt  O 

m 

•EXIT 
[EXIT] 


Nhan  BDI  ax its,  it  prints  tha  aaasaga  [BXIT]  and  raturns  control  to 
tha  oparating  systaa.  Tha  iaplicit  proapt  (>)  Indicatas  that  tha  CLI 
is  raady  to  accapt  a  naw  coaaand.  Tha  raaaindar  of  this  chaptar  aakas 
char.gas  in  tha  sourca  fila  SKEL.NAC  and  daaonatrataa  BDI  coaaanda  at 
tha  saaa  tiaa.  If  you  are  using  BDT  or  soaa  othar  aditor,  follow  tha 
changas  as  daaonstrated  and  aaka  thaa  in  your  fila  uaing  your  aditor. 
If  you  ara  using  DCL,  raaaabar  to  usa  tha  BDIT/BDI  or  BDIT/EDT 
coaaand . 
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Bxaapl*  2-2  Creating  th«  Skeleton  Fil*  8KBL.HAC 


>EPI  8KEL.HAC 

CCRlATIHe  NEN  FILCl 

INrUT 

(»      .  TITLE  0  8KELTN0  SOURCE   FILE 

m  .IDENT(9/01/ 

f 

I 

I  AUTHOR I  Z 

t 

t  .  ' 

»  CHANBESt 

»  ,   ,.■■ 

) 

I  MODULE  FUNCTION! 
I 

m 


SKELETON 


•PAGE  m  & 


I  BREAK  PAGE  FOR  PREFACE 


.SBTTL(^&rNBOL»  NACROf  DATA  DEFINITIONS 


m 


.LIST  ®TTH(S8  m 

.NLisT  mii£xm  m 

.HCALL  ®  EXIT»8  ®  ® 


LOCAL  SYNBOL  DEFINITIONSt 

m  ® 

LOCAL  MACROS t 

®  US 

LOCAL  DATA  BLOCKS! 

m  .PSECT  @  DATA>D>RU 

®  (E) 

FUNCTION  DETAILS! 

&  (E) 

<^   INPUTS! 

m        OUTPUTS! 

m        BIDE  EFFECTS! 

®  ® 

8.PA0E 
.SBTTL 
®      .PSECT 
t  START  CODE  HERE 
START! 
®  !© 
END!!@  EXITtS  ^  ® 

.END  <m  &  & 


BEX  IT 
CEXIT3 


ITERHlNAL  LlSTINO  NODE 
•SUPPRESS  BIN  EXTENSION 
(EXEC'S  EXIT  MACRO 


»EXIT  CLEANLY  TO  EXEC 

I  TELL  ASSEMBLER  END  OF  CODE 
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2.2.2  Creating  •  Source  Pll*  froa  th«  Skeleton 

After  you  create  the  skeleton  file,  you  can  uae  it  nany  tinea  to 
create  different  source  files  by  running  the  editor  again  as  described 
in  Section  2.2.1.   For  example: 

MCR>EDI  SKEL.MAC 
[00054  LIMES  READ  IN] 
[PAGE  1] 

e 

This  time  EDI  finds  the  file  you  just  created,  reads  it  into  menory, 
and  prints  an  asterisk  to  request  a  connand. 

The  EXIT  command  with  a  file  specification  creates  a  new  file  having 
that  name  and  containing  all  of  the  text  in  your  skeleton.  For 
example: 

*EXIT  FILE. MAC 
[EXIT] 


EDI  creates  either  the  new  file  FILE.MAC;1  in  your  directory  or,  if 
the  file  already  exists,  a  new  version  of  the  file.  It  retains  the 
input  file  SKEL.MAC.  You  can  repeat  this  process  to  create  as  many 
new  source  file^  as  you  need. 

At  this  point,  the  contents  of  SKEL.MAC  and  your  new  file  are  exactly 
the  same  —  typographical  errors  and  all.  Now  you  laust  use  editing 
commands  to  change  your  new  file  to  make  it  unique.  Section  2.3 
describes  some  of  these  commands  and  gives  examples  of  their  usage  to 
enable  you  to  perform  the  most  common  editing  functions. 

By  using  the  same  skeleton  file  each  time  you  want  to  create  a  new 
source  file,  you  save  typing  time  and  have  a  better  chance  of  creating 
consistent,  easily  readable,  and  well-documented  code.  After  you  have 
gone  through  Section  2.3  and  learned  the  editing  commands,  you  may 
want  to  correct  the  errors  in  the  skeleton  file. 


2.3   EDITING  THZ  SOURCE  PILE 

This  section  describes  how  to  use  a  subset  of  EDI  commands  to  edit  a 
source  file.  By  following  the  examples  in  this  section,  you  will 
create  three  source  files  that  you  can  use  in  subsequent  stages  of  the 
program  development  cycle. 

You  can  abbreviate  most  of  the  commands  in  EDI.  For  example,  the  EXIT 
command  can  be  abbreviated  EX.  The  descriptions  of  each  command 
include  (within  parentheses)  the  accepted  abbreviation,  if  one  exists. 
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2.3.1  Displaying  Taxt 

Use  the  EDI  command  to  access  a  source  file  to  edit.   For  example: 

MCR>EDI  FILE. MAC 
[00054  LINES  READ  IN] 
[PAGE  1] 

ft 

Two  keys,  RETURN  and  ESCAPE,  cause  EDI  to  move  forward  and  backward, 
respectively,  one  line  and  to  display  the  new  line.  By  using  these 
tiro  keys,  you  can  step  line  by  line  through  a  file.   For  example: 

*® 

.TITLE   SKELTN    SOURCE  FILE  SKELETON 

*(E) 

.IDENT   /Ol/ 
♦  IE) 

.TITLE   SKELTN    SOURCE  FILE  SKELETON 

* 

Typing  the  RETURN  key  twice  advances  the  pointer  two  times  and 
displays  each  line.  Typing  the  ESCAPE  key  moves  the  pointer  back  to 
the  previous  line  and  displays  the  line. 


TYPE  n  (TY  n) 


The  TYPE  n  command  displays  n  lines  t  a  time  but  does  not  alter  the 
line  position.   For  example: 

*TYPE  2 

.TITLE  SKELTN   SOURCE  FILE  SKELETON 
.IDENT  /Ol/ 

* 

The  2  in  the  TYPE  command  causes  EDI  to  display  the  curi'ent  line  and 
the  next  line.  If  you  give  tl^  TYPE  command  without  a  number,  EDI 
displays  the  current  line  (that  is,  one  line)  . 


LIST  (LI) 


The  LIST  command  displays  all  lines  in  the  buffer  starting  at  the 
current  line  and  stopping  at  the  last  line  in  the  buffer  (that  is,  ^nd 
of  buffer).   For  example: 

*LIST 

(all  lines  are  listed) 
♦type 

[♦BOB*] 

*EXIT 
[EXIT] 


The  LIST  command  positions  the  line  pointer  at  the  beginning  of  the 
buffer.  The  TYPE  command  shows  the  position  of  the  line  pointer.  EDI 
nrints  the  blank  line  it  maintains  at  the  beginning  of  the  buffer  and 
tfis  message  [*BOB*]  to  remind  you  that  the  line  pointer  is  at  the 
beginning  of  the  buffer.  EDI  always  keeps  a  blank  line  at  the 
beginning  of  the  buffer  to  ali^ow  you  to  insert  lines  before  the  first 
line  of  text  in  the  buffer. 
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2.3.2  Lijeatlng  Tast  and  Positioning  tho  Lino  Polntor 

Editing  •  filo  roquirvs  you  to  locato  a  lino  of  tost  In  tho  bufCor  and 
to  poaltlon  tho  pointer  to  that  lino.  Ihls  soctlon  doacriboa  aovoral 
of  tho  eoMMnda  aoat  coaaonly  uaod  in  oditlng  filos. 


BEGIN  (B),  END  (E) 


Tho  BEGIN  and  END  conaanda  poaltlon  tho  polntor  to  fixod  linoa  in  tho 
buffer  —  tho  boginning  and  onding  linoa.  Iho  END  conaand  alao  printn 
tho  laat  lino  of  tho  buff or.   Por  oxaaploi 

NCR>eDI  PILE. MAC 

(00054  LINES  READ  IN] 

(PAGE  11 

•END 

m    .BHD  9  a  91 }  TELL  ASSEMBLER  END  OP  CODE 

• 

Tho  END  coMiand  la  uaoful  for  quickly  asaoaalng  what  tho  laat  lino  in 
tho  buffor  i».  Tho  BEGIN  coaaond  la  holpful  in  quickly  poaitioning 
tho  polntor  at  tho  boginning  (or  top)  lino  of  tho  buffor,  thus 
enabling  you  to  aako  aultlpl*  paaa;*s  ovor  a  buffor.   Por  oxaaplot 

•BEGIN 
•TYPE 

(•BOB^l 

Bocauao  tho  BEGIN  coaaand  dooa  not  diaplay  any  tost*  you  can  uso  tho 
TYPE  coaaand  to  diaplay  tho  Cirat  lino  in  tho  buffor.  Tho  coaaand  in 
tho  axaaplo  ahowa  tha  blank  lino  at  tho  boginning  of  tho  buffor.  EDI 
prints  (•BOB^l  to  ahow  you  that  it  ia  positfonod  at  tho  boginning  of 
tho  buffor.   Por  oxaaplot 

•m 

m    .TITLE  m    SKELTM  m    SOURCE  PILE  SKELETON 

Typing  tho  RETURN  koy  advancoa  tho  polntor  and  dlsplaya  tho  lino,  as 
follows: 


LOCATE  (L) 


If  tho  tOKt  you  want  to  oxaaino  is  within  tho  buffor #  you  can  typo  tho 
LOCATE  coaaand  with  a  atriiig  to  bo  located.   Por  oxaaplot 

•LOCATE  MODULE 

I  MODULE  PUMCTION: 

* 

A  apace  ahould  aeparate  tho  coaaand  and  the  aoarch  atring  to  bo 
located.  EDI  diaplays  the  line  on  which  it  found  tho  flrat  occurrence 
of  the  atring.  If  EDI  dooa  not  find  the  atring,  it  prlnta  a  aoaaago 
Indicating  that  the  end  of  buffor  haa  boon  reached.   Por  osaaplet 

•LOCATE  NODULE 
{ftgOB«] 

• 
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After  an  unsucc«a>ful  ••arch,  EDI  l«av«s  th«  line  pointer  «t  th«  last 
Una  of  tha  buffar. 


PLOCATE  (PL) 


If  tha  atrlng  for  which  you  ara  aaarchinq  la  not  In  tha  buffar,  you 
can  uaa  tha  PLOCATE  coaaand  to  tall  EDI  to  aaarch  auccaaalva  buffara 
until  it  locataa  tha  atring.   For  axaaplai 

•BEGIN 
•PLOCATE  .END 

.END  m    99     m   :    TELL  ASSEMBLER  END  OF  CODE 

* 

EDI  aaarchaa  tha  buffar  atarting  at  tha  currant  lina.  If  tha  atring 
la  not  found  in  tha  buffar,  EDI  praaarvaa  tha  contanta  of  tha  buffar 
and  raadc  in  aorn  llnaa  from  tha  input  fila  to  fill  tha  buffar  again. 
It  printa  a  mta^aqm  tailing  tha  nuabar  of  linaa  aaarchad.  Mhan  EDI 
finda  tha  atring,  it  diaplaya  thw  lina  on  which  tha  atring  occura.  If 
EDI  doaa  not  find  tha  atring,  it  printa  a  aaaaaga  indicating  that  tha 
and  of  fila  has  baen  raachad.   For  axaapla: 

•PLOCATE  .ENDR 
l*EOF*l 

At  tha  and  of  fila  (aignalad  by  [•EOF*]),  EDI  laavaa  an  capty  buffar 
in  which  you  can  aithar  inaart  naw  taxt  (which  foliowa  all  tha  taxt 
currently  in  tha  fila)  or  axit  to  praaarvc  ^ny  changaa  aada  and  to 
atart  at  the  beginning  of  the  file  '^gcin.  Note  that,  once  EDI  haa 
praaerved  a  buffer,  you  cannot  go  back  to  it  except  by  atarting  at  the 
beginning  of  the  file  again.   For  axaaplat 

•EXIT 
[EXIT] 


You  car  alao  uaa  the  PLOCATE  coaaand  with  a  atring  known  not  to  axiat 
in  the  file  to  poaition  EDI  after  the  laat  line  of  the  file. 


RENEW  (REN) 


The  RENEW  coaaand  lets  you  read  new  lines  froa  the  input  file.   For 
exaaplet 

•EDI  FILE. MAC 

[000S4  LINES  READ  IN] 

[PAGE  1] 

•RENEW 

[•EOF^] 

[PAGE  2] 

•EXIT 

[EXIT] 


The  RENEW  coaaand  writes  the  li  jes  in  the  buffer  to  the  teaporary 
output  file  before  it  reads  in  new  lines  from  the  input  file.  If 
there  are  no  aore  linea  left  in  the  file,  EDI  signals  the  end  of  file. 
This  coaaand  is  useful  for  casually  inspecting  the  contents  of  a  file. 
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2.3.3  Changing  T«xt 

CHANGE  (C) 

The  CHANGE  connand  altars  text  on  tha  currant  lina,  allowing  you  tot 

1.  Raplaca  an  old  string  with  a  naw  string 

2.  Add  a  string  at  tha  start  of  a  lina 

3.  Dalata  a  string  from  a  lina 

Tha  command  raquiras  that  you  type,  within  character  delimiters,  the 
old  string  (the  text  to  be  altered)  followed  by  the  new  string.  The 
only  requirement  for  the  delimiting  character  is  that  it  does  not 
appear  in  either  the  old  or  the  new  string. i  A  convenient  character  to 
use  as  a  delimiter  is  tha  slash  character  (/) ,  as  shown  in  tha 
following  example: 

MCR>EDI  PILE. MAC 
[00054  LINES  READ  IN] 
[PAGE  1] 

*m) 

.TITLE  SKELTN    SOURCE  FILE  SKELETON 

*C  /SKELTN/NUMA/ ® 

.TITLE  NUNA      SOURCE  FILE  SKELETON 

After  you  enter  the  C  command,  EDI  searches  the  line  for  the  old 
string  (SKELTN)  and  replaces  it  with  the  new  string  (NUMA) .  EDI  then 
prints  the  changed  line  to  allow  you  to  verify  the  operation.  If  EDI 
cannot  locate  the  old  string,  it  prints  the  message  [NO  MATCH]  and 
reprints  the  prompt. 

To  save  typing  long  strings,  EDI  allows  you  to  include  an  ellipsis 
(...)  in  the  old  string.   For  example: 

*C  /SO. ..ON/COUNT  NUMBER  OF  A'S/ 

.TITLE   m       NUMA   (St   COUNT  NUMBER  OF  A'S 

* 

EDI  takes  the  characters  SO,  all  intervening  characters,  and  tha 
characters  ON  as  the  old  string.  The  ellipsis,  used  in  this  manner, 
reduces  the  amount  of  typing  required  to  specify  a  string  to  be 
changed.  Three  other  forms  of  the  ellipsis  allow  variations  of  the 
abbreviation: 

/.../  By  itself,  the  ellipsis  means  the  entire  line 

/old  string.../     From  old  string  to  the  end  of  the  line 

/...old  string/     From  the  beginning  of  the  line  to  old  string 

The  slash  characters  shown  as  delimiters  with  the  ellipsis  can  be  any 
unique  character. 


1.  The  ampersand  character  (6)  should  not  be  used  as  a  delimiter 
because  EDI  treats  it  as  a  concatenation  character.  If  you  must  use 
it  as  a  delimiter,  follow  the  special  procedures  presented  in  the  EDI 
chapter  in  the  RSX-llH/M-PLUS  Utilities  Manual  for  using  the 
Concatenation  Character  (CC)  command. 
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To  plac*  a  string  at  the  beginning  of  a  lina,  specify  the  null  string 
as  the  old  string.   For  exanple: 

*C  //OLD  STRING/© 

OLD  STRING  m     .TITLE  (9  NUMA  (9  COUNT  NUMBER  OP  A'S 

* 

EDI  replaces  the  null  string  at  the  beginning  of  the  line  with  OLD 
STRING  and  prints  the  changed  line. 

To  delete  a  string  from  the  line,  specify  the  null  string  as  the  new 
string  as  follows: 

•C  /OLD  STRING// gn 

(39    .TITLE  !9  NUMA  (9  COUNT  NUMBER  OP  A'S 

* 

EDI  replaces  OLD  STRING  with  the  null  string:  that  is,  it  deletes  OLD 
STRING  and  prints  the  changed  line. 

AP 

A  special  connand,  AP,  adds  a  string  at  the  end  of  a  line.  The 
connand  does  not  need  delimiting  characters  since  only  one  string  can 
be  specified.  Simply  specify  a  space  to  separate  the  command  and  the 
string  as  follows: 

•m 

.IDENT  /Ol/ 
*AP   9  ;  IDENTIFY  MODULE  VERSION 

.IDENT  /Ol/   (SI   ;  IDENTIFY  MODULE  VERSION 

After  adding  the  text  at  the  end  of  the  line,  EDI  displays  the  changed 
line. 

DPn 

To  remove  a  line  or  lines  from  the  text  in  the  buffer,  specify  the 
DP  n  command,  where  n  is  the  number  of  lines  to  be  deleted.  You  can 
use  the  TYPE  n  command  with  the  DP  n  command  to  display  the  lines  to 
be  deleted.   For  example: 

•TYPE  3 

; 

I 

; AUTHOR :Z 

•DP  2 

; AUTHOR :Z 

* 

The  TYPE  3  command  displays  the  current  line  and  two  succeeding  lines 
(the  pointer  remains  positioned  at  the  current  line).  The  DP  2 
command  deletes  the  current  line  and  one  succeeding  line.  EDI  moves 
the  pointer  to  the  line  after  the  last  one  deleted  and  prints  that 
line. 
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EXIT  (EX) 


After  changing  t«xt  in  th«  file,  clos*  th«  editing  •••■ion,  •• 
follows  I 

•exit 

[EXIT] 


Th«  EXIT  coaaand  without  a  fil*  naa*  cr«at««  a  n*w  var^ion  of  the 
current  fil*  and  copias  the  reaainder  of  the  file  to  the  new  version. 
Becauae  exiting  preaervee  the  edite  you  have  aade  to  that  point,  you 
•hould  exit  fairly  often  froa  a  lengthy  editing  ••••ion.  If  a  ay^tea 
craah  occurs,  EDI  retaina  th«  old  vereion  of  your  file  (that  is,  it 
retaina  the  edita  up  until  you  last  exited)  but  does  not  retain  the 
changea  you  are  aaking.  Frequent  exita  ainiaise  the  aaount  of  editing 
that  can  be  lost  if  a  systea  craah  occurs. 


2.3.4  Inserting  Code  In  the  Source  Pile 

INSERT  (I) 

The  INSERT,  or  I,  coaaand  allo%rs  you  to  add  aultiple  linea  of  text  in 
the  source  file.  To  insert  code  in  the  source  file  FILE. MAC,  use 
positioning  coaaands  to  loc«.Le  the  line  preceding  where  you  want  to 
place  the  new  aaterial.  Ihe  I  coaaand  places  new  lines  in  the  buffer 
after  the  current  line.   For  exaaple: 

NCR>EDI  FILE. MAC 
[00052  LINES  READ  INl 
[PAGE  1] 
•L  FUNCTION: 
;  MODULE  FUNCTION: 
*I® 

;      THIS  NODULE  LOADS  A  BUFFER, 
f      COUNTS  THE  NUMBER  OP  A'S  (UPPER 
f      CASE  ONLY)  IN  THE  BUFFER,  CONVERTS 
f      THE  NUMBER  TO  OCTAL,  AND  REPORTS 
I      THE  NUMBER  OF  A'S  FOUND.  ST) 

m 

e 

The  L  coaaand  (for  LOCATE)  positions  EDI  to  the  line  preceding  where 
you  want  to  place  the  new  lines.  Typing  the  I  coaaand  followed  by  the 
RETURN  key  places  EDI  in  insert  aode.  After  you  type  the  lines,  press 
the  RETURN  key  twice  in  succession  to  leave  inaert  aode. 

Continue  using  positioning  and  editing  coaaands  to  type  in  the 
reaainder  of  the  source  prograa  shown  in  Exaaple  2-3. 
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Bxaapl*  2-3  Sourc*  Cod*  for  FILB.NAC 


•TITLE 
.IKNT 


NUHA     COUNT  NUMBER  OF  A'S 

/Ol/     I  IBENTirV  NODULE  VERSION 


I 

I 

I  AUTHOR i  Z 
I 

t 

I  CHANOESt 

I 


I  HOBULE  FUNCTION) 


t 

f 

I 
f 


THIS  NODULE  LOADS  BUFFER r 
COUNTS  THE  NUNBER  OF  A' 8  <UFPER 
CASE  ONLY)  IN  THE  BUFFER*  CONVERTS 
THE  NUNBER  TO  OCTAL*  AND  REPORTS 
THE  NUNBER  OF  A'S  FOUNB. 


.PASC 

.SBTTL 
.LIST    TTN 
.NLIST   BEX 
.NCALL   EXITtS 


I  BREAK  FACE  FOR  PREFACE 
SYNBOL*  NACRO*  DATA  DEFINITIONS 

I  TERMINAL  LISTIN6  NODE 
I  SUPPRESS  BIN  EXTENSION 
I  EXEC'S  EXIT  MACRO 


»  LOCAL  SYMBOL  BEF INI T IONS t 
MSOLEN   -  NUMEND-M88 
SIZ      «  80. 
SIZA     ■  6, 

I 


I  LOCAL  MACROS t  NONE 


I  LOCAL  DATA  BLOCKS t 
t 

.P8ECT   OATA*D»RH 


At 

.ASCII 

BUFlt 

.BLKB 

Nsei 

.ASCII 

NUMAt 

.BLKB 

NUNEND 

■ 

NUNCt 

.BLKW 

• 

/A/  t    DEFINE  AN  A 

SIZ  I  DEFINE  BUFFER 

/THE  NUMBER  OF  A'S  18  / 

SIZA  *  OEFINE  OCTAL  COUNT 

I  ENB  OF  NESSAOE 
1  I  NUNBER  OF  CHARS  TYPED 
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Exeunple  2-3  (Cont.)   Source  Code  for  FT  >E.MAC 

I  FUNCTION  DETAILSt 
INPUTS t 


•UFl  IS  LOADED  WITH  CHARACTERS 

OUTPUTS t 

NUHA  HOLDS  THE  NUNIER  OF  A'S 

SIDE  EFFECTS)  NONE 


i  START  CODE  HERE 


.PAGE 

.SBTTL 

ROUTINE  TO  CUUNT  A'S 

.P8ECT 

STARTS 

HOV 

•BUFlrRO 

LOAD  BUFFER  ADDR 

''' 

NOV 

•SIZtKl 

LOAD  BUFFER  SIZE 

CALL 

READ 

READ  FROH  TTY 

TST 

R2 

ANY  CHARS  IN  BUFFERT 

DEC 

END 

IF  NONE*  FINISH  UP 

r.LR 

Rl 

INIT  •  OF  A'S  C0L.4TER 

NOV 

R2»NUHC 

SAVE  •  OF  CHARS  TYPED 

io«: 

■  ■.. 

CHPB 

<RO>'f>A 

IS  CHAR  -  AT 

SHE 

20» 

IF  NO*  BET  NEXT  CHAR 

INC 

Rl 

COUNT  AN  A 

20«t 

'.■'  '■'■';  ,'■  ■• 

DEC 

R2 

ONE  LESS  CHAR 

BNE 

10$ 

IF  NORE*  CONPARE  NEXT 

.PAOE 

..'.-,■■■■'.'■  ■  ,  V 

.SBTTL 

TRANSLATE  COUNT 

TO  OCTAL 

NOV 

•NUHA4-6rRO 

SET  PTR  TO  OCT^L  • 

NOV 

•5»R2 

SET  COUNT  OF  DIBITS 

30«t 

■'■   ,  , 

NOV 

Rlf-<SP) 

STACK  IS  TENP  AREA 

•  IC 

•177770fS8P 

STRIP  LOU  3  BITS 

ADD 

•«OfOSP 

NAKE  OCTAL  DIOIT 

NOVB 

(8P)4»-(R0) 

STORE  OCTAL  DIOIT 

ASR 

Rl 

SHIFT  TO 

A8R 

Rl 

NEXT 

ASR 

Rl 

3  BITS 

DEC 

R2 

ONE  LESS  DIOIT 

BNE 

30* 

IF  NOREi  REPEAT 

NOV 

•NSOfRO 

LOAD  ADDR  OF  BUFFER 

NOV 

•H80LEN>Rt 

LOAD  SIZ  OF  NE8SA6E 

CALL 

URZTE 

REPORT  THE  RESULTS 

ENDt 

EXIT$S 

EXIT  CLEANLY  TO  EXEC 

.END 

TELL  ASSEMBLER  END  OF  CODE 
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Aft«r  you  hav*  typad  In  th«  cod*,  ua«  tha  tachnlquaa  daacrlbad 
pravloualy  to  craata  two  naw  aourca  filaa,  PILBA.NAC  and  PILES. MAC, 
froa  tha  akalaton  fila.  Iha  coda  for  thaaa  two  fllaa  Is  shown  in 
txasplas  2-4  and  2-S.  Ihasa  two  fllas  and  tha  fllQ  PIU.NAC  will  ba 
usad  in  Chaptar  4  to  build  and  tast  a  task.  Tou  aay  want  to  adit  tha 
skalaton  fila  bafora  you  craata  tha  two  now  sourca  fllas. 


taaapla  2-<  Sourca  Coda  for  PILIA.NAC 


.TITLE   TTRCAB   TCftNINM.  REM  ttUM9UTINE 
.IKNT   /•!/ 


MlTNMt  SEP   S-MM-tl 


CNMMEtl  NONE 


NOeULE  PUNCTIONt 

TNIt  NOMLE  NEAM  A  LINE  PMM  A 
TERNINAL  INTO  A  SUPPER 


.PAOE  I  SREAK  PAOE  POR  PREP ACE 

.SSTTL  STNSOL*  MACRO*  SATA  SEPINITI0N8 

.LIST  TTN  I  TERMINAL  LISTINS  NOSE 

.NLIST  SEX  f  SUPPRESS  SIN  EXTENSION 

.NCALL  OIOSStUTSEtS 

I 

I  LOCAL  SYNSOL  SEPINITIONSt 

EPNl  •  I  , 

LUN9  -  S 
I 

I 

I  LOCAL  MACROS i  NONE 


I 

I    LOCAL    SATA   SLOCKS t 

I 

.PSECT   SATAtSvRN 


lOSTI 
I 


.SLKtt 


f  SEP  10  STATUS  HSS 


^ 


2-21 


CSlJiTIHC   PMCRO-li    BOtmCB   FILES 


BxMpl*   2-4    (Oont.)      8eure«  Cod*  for   PILIA.NAC 


PUNCTION   •CTAILtS 

INPUTS t    M  ■  ABMtlM  Of   MITFEII  TO  LOAD 
Rl   -  LENtTN   IN  •¥?!•  Of   MlfPCR 


OUTKITtt 
•IK  irFKCTtt 


R2   -  NUHKR  OF   CNMIS   (BYTES)   IIEAB 

lOT  IF  imoii 


.FASC 

.SBTTL   START  OF  COJC 

.FSeCT 
f  START  COBE  HERE< 
REABtl  I  REFINE  ENTRY  POINT 

OIOSS    •I0.RLB»*LUNtf»«EFNt»»P!9ST»*<^0»t)l> 

010 


10«t 


BCS 

10« 

MTSEM 

•EFNl 

TSTB 

lOST 

BLT 

to« 

NOV 

I0ST«2fR2 

RETURN 

NOV 

•BSNfRO 

NOVO 

lOSTrRl 

lOT 

.ENO 

3IR  PRRANETERSt 

RLB  IS  REAR  LOO  BLOCK 
LUNS  •  TKB  SKFAIliT 
EFNl  IS  FVENT  FLA)  tl 
I08T  >  STATUS  A..;ZA 
<>  -  PARANETER  LLSr 
RO  •  START  OF  BUFFER 
Rl  -  SIZE  OF  BUFFER 
IF  SET*  BIR  ACCEPT  ERROR 
MAIT  FOR  10  CONPLETE»EF  1 
CHECK  10  STATUS 
IF  LTf  10  ERROR 
SAVE  •  OF  BYTES  REAR 
00  BACK  TO  CALLER 

SAVE  OIR  STAT  MB 

SAVE  10  STAT  BYTE 

FORCE  SST  EXIT 

TELL  ASSENBLER  ENB  OF  COBE 
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tKMipl*   2-5     Source  Cod*   for   PILtB.NAC 

.TITLE      TTIMIT      TCMUNM.  MtlTC   tUMOUTlNC 
.IKNT      /Ol/ 

AUTNOKt    KF   t-AIM-tl 


CNAIMCSt  NONE 


HOOULE  FUNCTION t 

THIS  NODULE  MtlTEl  A 
LINE  FNON  A  lUFFER  TO 
A  TERNINAL 


.FAOE  I  MEAK  FAOE  FON  PREFACE 

.••TTL  tVNMN.*  NACM»  tATA  KFINITIONt 

.LIST  TTN  t    TERNINAL  LItTINO  NODE 

.NLI8T  DEX  f  tUFFItEtS  DIN  EXTENSION 

.NCALL  0IO«SfNTSE«S 


LOCAL  SYNDOL  DEFINITIONS! 
EFNl     -  1 
LUNS    •  S 


LOCAL  NACROSt  NONE 

LOCAL  DATA  SLOCKS t 

.PSECT   DATAtDtRM 
OSTt    .DLKM    2 

FUNCTION  DETAILS! 
INPUTS! 


f  DEF  10  STATUS  MDS 


t 


DO  -  ADDN  OF  DUFFER  TO  UNITE 
Rl  >  LENOTH  IN  DYTES  OF  DUFFER 
OUTPUTS! 

SUCCESS  IN  10ST 
SIDE  EFFECTS!  lOT  IF  ERROR 
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Ixmpl*  2-5  (Cent.)   Source  Cod*  for  PILBB.NAC 

.tBTTL   BTAMT  OF  CODE 
.PBCCT 
I  START  CODE  HCRC 
WRITE! t  I  DEf  ENTRY  POINT 

QlOtS    •IO.IILB»«LUNS»tEFNl»t«IOST»»<RO»RltMO> 

I  QIOM  PARANETERSt 

10. MLB  FUNCTION  CODE 
LUN9  <TKB  DEFAULT) 
EFNl  IS  EVENT  FLAO  1 
STATUS  AREA  >  lOST 
PARANETER  LIST  <> 
RO  ■  START  OF  BUFFER 
Rl  -  •  OF  CNAR8  TO  WRITE 
40  -  OUTPUT  <CR>»<LF> 
IF  SETt  DIR  ACCEPT  ERROR 
WAIT  FOR  10  CONPLETE 
CHECK  10  STATUS 
IF  LT»  10  ERROR 
00  BACK  TO  CALLER 


lOtt 


BC8 

lot 

WTSEtS 

•EFNl 

TSTB 

I08T 

BLT 

lot 

RETURN 

NOV 

tDSW»RO 

NOVB 

I0ST»R1 

lOT 

.END 

SAVE  DIR  STAT  WD 
SAVE  10  STAT  VALUE 
SST  DUNPS  TASK  REOS 
TELL  ASSEHDLER  END  OF 


CODE 


2.4  GUIDE  TO  FURTHER  RBAOIMG 

The  sections  or  chapters  in  the  following  documents  contain  additional 
infornation  on  the  subjects  described  in  this  chapter. 


Docuaent 

PDP-11  NACRO-11  Language  Reference  Manual 

Chapter  2,   Source  Progran  Pornat 
Appendix  E,   Sanple  Coding  Standard 
Section  6.1,  Listing  Control  Directives 
Section  6.6,  Terminating  Directives 
Section  6.7,  Program  Sectioning  Directives 
Section  7.8,  MACRO  Library  Directive:  .MCALL 

R8X-11M/M-PLUS  Task  Builder  Manual 

Section  2.1,  Linking  Object  Modules 

Section  10.1.28,  SG  (Segregate  Program  Sections) 

Section  10.1.32,  SQ  (Sequential  Program  Sections) 

RSX-llM/M-PLUS  Utilities  Manual 

Chapter  2,  Line  Text  Editor  (EDI) 

RSX-llM/M-PLUS  Executive  Reference  Manual 

Section  1.4.1,  Macro  Name  Conventions 
Chapter  5,  Task  Exit  (EXIT$S) 
Chapter  5,  Queue  I/O  Request  and  Wait 
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CHAPTER  3 
ASSBMBLIMG  AMD  CORRBCTIMG  A  PROGRAM  NODULE 


This  chapter  describes  a  few  uses  of  the  MACRO-11  Asseabler,  soac  of 
the  common  types  of  codin.,  errors,  some  ways  to  uncover  and  correct 
errors,  and  the  way  to  generate  a  cross-reference  listing. 

The  material  in  this  chapter  assumes  that  you  have  created  the  three 
source  files  as  described  in  Chapter  2. 


3.1   PERFORMING  A  DIAGNOSTIC  RUN  ON  A  SOURCE  PILE 

Your  first  use  of  the  MACRO-11  Assembler  on  a  source  file  should  be  to 
perform  a  diagnostic  run.  You  run  the  assembler  only  to  check  for 
general  errors,  not  to  produce  an  object  module  or  a  listing  file. 

To  perform  a  diagnostic  run  from  a  [X:l  terminal,  type  the  following 
command  line: 

DCL>NACRO/NOOBJECT/DISABLE:GLOBAL  FILE 

(any  error  messages  appear) 


The  source  file  is  named  PILE. MAC,  but  because  the  MACRO  command 
defaults  to  a  file  type  of  MAC,  the  file  type  need  not  be  specified. 
Normally,  the  MACRO  command  is  used  to  create  an  object  module,  so 
that  the  /NOOBJECT  qualifier  is  necessary  to  override  this  standard 
function.  The  MACRO  command  does  not  produce  a  listing  file  unless 
you  request  one  with  the  /LIST  qualifier.  When  you  do  not  make  a 
listing  file,  any  errors  that  result  from  assembly  are  listed  directly 
on  your  terminal. 

The  /DISABLE :GLOBAL  qualifier  causes  KACRO-11  to  disable  the  setting 
of  undefined  symbols  to  global  and  external.  Ordinarily,  when 
MACRO-11  finds  a  symbol  that  is  not  defined  in  the  source  file,  it 
assumes  that  the  reference  is  to  a  symbol  defined  externally,  that  is, 
in  another  module.  By  disabling  this  feature  for  your  diagnostic  run, 
you  tell  the  assembler  to  flag  any  potential  global  references  as  an 
undefined  symbol  error.  Since  you  already  know  which  symbols  in  your 
source  file  are  global,  this  disabling  method  is  a  convenient  way  to 
catch  typographical  errors  in  other  symbol  names. 

To  perform  a  diagnostic  run  from  an  MCR  terminal,  type  the  following 
command  line: 

MCR>MAC  /DS:GBL-FILE 

(any  error  messages  appear) 
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The  right  side  of  th«  equal  sign  gives  the  specification  of  the  source 
file.  The  assenbler  searches  for  the  file  naned  PILE. MAC  in  your  UPD. 
The  assenbler  applies  the  type  MAC  as  a  default.  Because  there  are  no 
file  specifications  on  the  left  side  of  the  equal  sign,  MACRO-11  does 
not  produce  any  object  module  or  listing  file.  When  you  do  not 
specify  a  listing  file  in  the  comnand  line,  the  assenbler  prints  on 
the  input  terninal  the  lines  that  generated  errors  and  reports  the 
total  number  of  errors  found. 


The  left  part  of  the  command  line  (/DS:GBL)  causes  MACRO-11  to  disable 
the  setting  of  undefined  synbols  to  global  and  external.  Ordinarily, 
trhen  MACRO-11  finds  a  symbol  that  is  not  defined  in  the  source  file, 
it  assumes  that  the  reference  is  to  a  symbol  that  is  defined  external 
to  the  module  (in  another  module).  (The  notation  GX  in  the  listing 
symbol  table  denotes  a  global  and  externally  defined  symbol.)  By 
disabling  this  feature  in  the  diagnostic  run,  you  tell  the  assembler 
to  flag  any  potential  global  reference  with  an  undefined  symbol  error. 
This  disabling  method  is  a  convenient  way  to  catch  typographical 
errors  in  symbol  names  at  assembly  time  rather  than  later  when  you 
link  your  object  modules  together. 

The  appearance  of  MACRO-11  messages  at  the  terminal  during  the 
diagnostic  run  indicates  that  your  module  contains  errors.  If  the 
assembler  does  not  find  any  errors,  it  simply  returns  control  to  the 
Executive  and  MCR  prints  its  prompt.  Errors  in  the  assembly  are 
denoted  by  single  letter  codes  printed  at  the  beginning  of  the  faulty 
statement.  These  errors  are  summarized  in  an  appendix  of  the  PDP-11 
MACRO-11  Language  Reference  Manual. 


The  only  errors  that  should  appear  from  the 
following: 


diagnostic   run  are  the 


U     71  000010   004767 
D     99  000110   004767 
ERRORS  DETECTED:   2 
/DS:GBL-PILE 


CALL     READ      ;  READ  PROM  TTY 
CALL     WRITE     ;  REPORT  THE  RESULTS 


The  two  undefined  symbols  READ  and  WRITE  are  the  entry  points  defined 
in  the  source  files  FILEA.MAC  and  FILES. MAC.  These  symbols  are  to  be 
resolved  by  TKB.  (Note  that  this  example  was  generated  by  the  MCR 
command  MAC  /DS:GBL>PILE.) 


3.2   TYPICAL  ERRORS  BNCOUMTERED  DURING  ASSEMBLY 


Four  error  codes  cover  the  majority  of  errors  made  in  an  assembly 
language  source  file.  The  following  sections  describe  some  of  the 
most  common  conditions  under  which  these  error  codes  are  generated. 


3.2.1   The  NACRO-11  Errr r  Code  A 

Error  code  A  indicates  a  general  assembly  error.   Most  of  these  errorn 
are  caused  by  typing  mistakes  such  as  the  following: 

e   Omitting  the  semicolon  (;)  from  a  comment 

The  semicolon  separates  your  comment  from  the  portion  of  the 
statement  that  the  assembler  evaluates.  If  you  omit  the 
semicolon,  MACRO-11  attempts  to  evaluate  your  comment  as  part 
of  the  rest  of  the  statement  line. 
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•  OMittlng  th«  p«riod  fron  a  HACRO-11  dir«ctiv* 

The  leading  period  (.)  in  the  operator  field  tells  the 
aasenbler  that  the  atatenent  contains  a  MACRO-11  directive. 
If  yoi  forget  to  include  the  period  on  a  directive,  the 
aasenbler  cannot  evaluate  the  operator  as  a  directive.  As  a 
result^  error  code  A  is  generated,  the  directive  and  its 
arguaients  are  given  a  value  of  0,  and  they  are  designated  as 
global  symbols. 

e  Misspelling  a  PDP-11  instruction  mnemonic 

If  you  misspelled  a  PDP-11  instruction  mnemonic  (for  example, 
MOVE  instead  of  MOV) ,  the  assembler  can  evaluate  the  operands 
but  not  the  operator.  The  PDP-11  MACRO- 11  Language  Reference 
Manua.\  lists  all  the  mnemonics  alphabetically.  (These 
mnemonics  make  up  the  permanent  symbol  table  (PST)).  The 
PDP-11  Programming  Card  also  contains  all  the  instruction 
mnemonics. 

e   Forming  an  illegal  symbol 

The  first  character  of  a  symbol  must  not  be  a  numeral. 

e  Not  properly  delimiting  a  directive  argument 

Many  MACRO-11  directives  require  a  character  or  argument 
string  to  begin  and  end  with  a  certain  delimiting  character. 
If  you  use  the  wrong  character  or  omit  one  of  the  delimiters, 
the  assembler  cannot  properly  match  the  delimiters  and 
therefore  cannot  evaluate  the  directive.  For  example,  the 
.ASCII  directive  requires  the  charact<ir  string  to  begin  and 
end  with  the  same  delimiting  character. 

Another  type  of  general  assembly  error  Involves  general  addressing 
errors.  The  typical  addressing  error  Is  to  exceed  the  range  of  a 
branch  Instruction  (that  is,  branching  more  than  128  words  backwards 
or  127  words  forwards).  Tc  correct  this  type  of  error,  replace  the 
branch  Instruction  with  code  to  test  the  proper  condition,  and  with 
the  JNP  Instruction  to  transfer  control. 

Also  common  as  a  general  assembly  error  are  Illegal  forward 
references.  If  you  define  a  symbol  based  on  atiother  symbo''  defined  by 
a  forward  reference,  the  assembler  cannot  evaluate  th/t  reference.  For 
example: 

A  -  B  +  10. 
C  -  A  +  10. 

The  assembler  jannot  evaluate  the  symbol  A  because  B  Is  not  yet 
defined. 


3.2.2  The  MACRO-11  Error  Code  U 

Error  code  U  signals  an  undefined  symbol  error.  This  error  usually 
occurs  because  (1)  a  symbol  name  on  the  .MCALL  directive  was 
misspelled  or,  (2)  reference  was  made  to  a  local  label  that  does  not 
exist  in  the  current  local  symbol  block. 
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3.2.3  Th«  NACRO-11  Error  Cod«  0 

Irror  code  0  Indlcatos  quostionabl*  syntax.  This  arror  usually 
raaults  fro*  oithor  including  too  aany  (or  too  faw)  arguaants  in  a 
diractiva  or  spaclfying  an  incorract  nuaibar  of  operands  on  an 
instruction.  In  addition,  this  arror  occurs  whan  you  oait  tha 
saaicolon  froa  a  coaaant  and  tha  assaablar  attaapts  to  evaluate  the 
couaent  aa  part  of  the  stateaent. 


3.2.4  The  NACRO-ll  Error  Code  E 

Error  code  B  aeans  that  you  have  oaitted  the  .END  directive  froa  the 
asseably  language  source  file.  If  the  asseabler  does  not  find  the 
.END  directive,  it  generates  error  code  E  with  a  line  nuaber  of  0 
after  the  last  stateaent  in  the  listing  file. 

Error  code  B  also  aay  indicate  an  expression  overflow.  If  the 
asseabler  encounters  a  nested  expression  that  is  too  coaplex,  it 
generates  error  code  E  and  denotes  the  point  of  the  overflow  with  a 
question  aark  (?).  To  clear  the  error  condition,  either  siaplify  the 
expression  or  ask  your  systea  aanager  to  build  HACRO-11  with  a  larger 
stack. 


3.3  GEMERATIMG  A  PROGRAM  MODULE  AMD  A  LI8TIMG 

After  you  correct  the  errors  uncovered  in  the  diagnostic  run,  you  are 
ready  to  produce  an  object  aodule  and  a  listing  file.  The  following 
DCL  coaaand  line  produces  an  object  aodule  and  a  listing  file: 

DCL>MACRO  PILE/LIST 

(error  suaaary  printed) 


This  coaaand  line,  like  the  coaaand  line  for  the  diagnostic  run, 
assuaes  default  file  types  for  th^  object  file  and  the  listing  file. 
The  asseabler  creates  an  object  aodule  called  PILE. OBJ.  The  /LIST 
qualifier  causes  the  aaseabler  to  create  a  file  called  PILB.LST.  It 
is  good  prograaaing  practice  to  use  the  asseabler  defaults  for  file 
types  and  file  naaes.  Using  the  defaults  helps  you  differentiate  file 
types  and  groups  aasociated  files  under  the  saae  naae.  If  you  wish  to 
use  other  naaes  and  file  types,  you  can  override  the  defaults  by 
supplying  coaplete  file  specifications  au  arguaents  to  the  /LIST  and 
/OBJECT  qualifiers. 

Mote  that  the  /LIST  qualifier  is  added  to  the  file  specification 
rather  than  to  the  MACRO  coaaand  in  the  exaaple.  This  placeaent  of 
the  qualifier  causes  a  listing  file  to  be  created  in  your  directory, 
but  the  file  is  not  printed  on  the  line  printer.  A  MACRO  coaaand  line 
in  the  following  foraat: 

DCL>MACRO/LIST  PILE 

(error  suaxary  printed) 


still   causes  th'*   listing   file   PILB.LST  to   be  created   in  your 
directory,  but-  the  file  is  al.*'>  printed  on  your  systea'8  Hne  printer. 
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For  the  tin*  baing,  you  should  us*  th*  /LIST  qualifier  as  a  fila 
spacif icatlon  qualifiar,  to  kaap  from  printing  too  many  copies. 
During  the  program  development  cycle,  you  create  many  files  for  which 
you  do  not  need  a  permanent  copy.  It  is  easier  and  less  wasteful  to 
examine  a  listing  file  at  your  terminal  than  to  generate  numerous 
printed  copies  of  listing  files  that  must  be  discarded  because  of 
minor  errors.  After  you  attain  an  error-free  assembly,  you  can  print 
a  copy  of  the  latest  version  of  the  listing  file. 

Nhen  you  request  a  listing  file,  the  errors  are  printed  In  the  file, 
not  on  your  terminal.  All  you  see  on  your  terminal  is  a  message 
giving  the  total  number  of  errors  found.  If  no  message  appears,  there 
are  no  errors.  Note,  however,  that  freedom  from  assembly  errors  does 
not  guarantee  that  the  program  will  run  properly. 

The  following  command  line  performs  the  same  functions  from  an  MCR 
terminal t 

MCR>MAO  FILE;,FILE/-SP-FILE 

(larror    summary  printed) 

> 

This  command  line,  like  the  command  line  for  the  diagnostic  run, 
depends  on  default  file  types  that  MACRO-11  automatically  assigns. 
The  leftmost  file  specification  creates  an  object  module  called 
PILE. OBJ.  The  file  type  OBJ  denotes  that  the  file  is  an  object 
module. 

The  comma  following  the  object  file  specification  in  the  command  line 
is  a  separating  character  that  is  required  to  distinguish  different 
file  specifications  in  command  lines. 

Following  the  comma  in  the  command  line  is  the  listing  file 
specification  that  creates  the  file  called  FILE.LST.  The  file  type 
LST  denotes  that  the  file  is  a  listing  of  source  code  produced  by  an 
assembler  or  compiler. 

It  is  good  programming  practice  to  use  the  assembler  defaults  for  file 
types  and  to  apply  the  name  of  the  source  file  to  both  the  object  and 
listing  files.  Using  the  defaults  helps  you  to  differentiate  types  of 
files  and  keeping  the  same  name  helps  relate  different  types  of  files 
to  the  proper  source  file. 

The  designation  /-SP  following  the  listing  file  specification  in  the 
command  line  inhibits  automatic  spooling  of  the  listing  to  the  line 
printer.  During  the  program  development  cycle,  you  create  many  files 
for  which  you  do  not  need  a  permanent  copy.  It  is  easier  and  less 
wasteful  to  examine  a  listing  file  at  your  terminal  than  to  generate 
numerous  copies  of  listing  files  that  must  be  discarded  because  of 
minor  errors.  After  you  attain  an  error-free  assembly,  you  can  spool 
a  copy  of  the  latest  version  of  the  listing  file  retained  on  your 
disk. 

When  you  request  a  listing  file  in  the  assembly,  MACRO-11  does  not 
print  error  lines  on  the  terminal.  Instead,  if  the  assembler  detects 
any  errors,  it  prints  a  message  giving  the  total  number  found.  If  the 
assembler  finds  no  errors,  it  simply  exits.  The  absence  of  a  summary 
of  error  messages  from  the  assembler  means  an  error-free  assembly.  If 
there  are  errors,  you  can  examine  the  listing  file  at  the  terminal. 
However,  an  error-free  assembly  does  not  guarantee  that  the  program 
will  run  properly. 
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You  can  isau*  tha  followinq  coaimand  linea  to  aaaambla  tha  two  othar 
aourca  filaa,  PILEA.MAC  and  PILEB.MAC,  which  you  craatad  ualng  tha 
procaduraa  dascribad  in  Chaptar  2t 

DCL>MACRO   PILBA/LIST 
iKLMACRO   PILBB/LIST 

or 

NCRMAC  PILCA,PILeA/-8P«PILBA 
NCR>MAC  PILBB,PILBB/-8P-PILEB 

Tha  two  conaand  linaa  craata  tha  objact  modulas  PILEA.OBJ  and 
PILBB.OBJ  that  you  will  naad  to  link  into  your  taak  in  Chaptar  4. 


3.4   BXAMINING  A  LISTING  AT  THB  TERMINAL 

Usa  tha  TYPE  connand  to  display  tha  listing  £ila  at  your  tarminal,  as 
shown: 

DCL>TYPE  PILE.LST 

(fila  appaars  on  scraan) 

> 

Proa  an  NCR  tarninal ,  you  can  run  tha  Paripharal  Intarchanga  Progran 
(PIP)  to  transfer  a  copy  of  your  listing  from  your  disk  to  your 
tarainal.   The  following  command  line  starts  the  transfer: 

MCR>PIP  TI:-PILE.LST 

(file  appears  on  screen) 

>  .        •  <  ■ 

In  the  part  of  the  command  line  to  the  left  of  the  equal  sign,  the 
designation  TI:  specifies  your  terminal  (that  is,  the  terminal 
hiitiating  the  request)  as  the  output  device. 

NOTE 

If  you  omit  the  colon  from  TI:,  PIP 
creates  a  new  file  called  TI  in  your  UPD 
and  copies  the  input  file  to  it. 


To  the  right  of  the  equal  sign  is  the  input  file  specification  with 
both  a  name  and  type.  Por  PIP,  you  must  specify  a  file  type  because 
it  does  not  apply  a  default  fila  type  for  you.  (Without  a  file  type, 
P  P  looks  for  a  file  with  no  type,  that  is,  a  file  with  a  null  type.) 

You  can  use  control  commands  to  temporarily  stop  and  restart  the 
display,  and  to  alternately  suppress  and  resume  the  output  request. 
The  commands  are  summarized  in  Table  3-1. 
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Tabl*  3-1 
Tarnir.al  Output  Control  Coanands 


Conaand 

Effect 

CTRL/S 
CTRL/Q 
CTRL/0 

T«Bporarily  stops  the  display 

Restarts  the  display  stopped  by  CTRL/S 

Alternately  suppresses  and  resumes 
the  output  to  the  terminal 

The  CTRL/S  and  CTRL/Q  commands  are  used  together  to  freeze  the  display 
on  the  screen  and  to  request  more  lines  to  be  displayed.  While  the 
CTRL/S  command  is  in  effect,  you  can  read  what  is  on  the  screen.  The 
CTRL/Q  command  tells  the  system  to  restart  the  display  where  it  left 
off  tfhen  it  sensed  the  CTRL/S  command. 


The  CTRL/0  command  is  used  to  suppress  unwanted  o 
tells  the  system  to  stop  sending  characters 
program,  however,  continues  processing  but  simply 
output.  (While  CTRL/0  is  in  effect,  the  sys 
input  and  does  not  echo  any  characters  typed  at 
typing  CTRL/0  again,  you  tell  the  system  to 
terminal.  By  typing  successive  CTRL/Os,  you  c 
portions  of  the  output  until  the  program  reaches 
the  program  finishes  processing  the  output  reques 
effect,  the  system  automatically  reenables  Iceyboa 
appears  on  the  terminal. 


utput.  The  command 
to  the  terminal.   The 

omits  displaying  the 

tern  disables  keyboard 

the   terminal.)   By 

resume  output  to  the 
an  skip  unnecessary 
the  correct  part.  If 
t  while  CTRL/O  is  in 
rd  input  and  a  prompt 


3.5   GBMBRATING  A  CROSS-RBFERENCE  LISTING 

Worthwhile  additions  to  the  assembly  listing  are  the  symbol  and  macro 
cross-reference  listings.  These  listings  give,  in  alphabetical  order, 
each  symbol  and  macro  name  defined  or  referred  to  and  the  number  of 
the  page  and  line  in  the  listing  where  the  definition  or  reference 
occurs.   Prom  a  DCL  terminal,  type  the  following  command  line: 

DCDMACRO/NOOBJECT  PILE/CROSSREPERENCE 

(any  errors  cause  total  number  to  be  printed) 


Note  that  the  command  line  does  not  include  the  /LIST  qualifier.  The 
/CROSS_REPERENCE  qualifier  implies  the  /LIST  qualifier  since  the 
cross-Tcference  listing  is  attached  to  the  assembly  listing.  If  you 
wish  to  have  the  listing  printed,  use  /CROSS_REPERENCE  as  a  command 
qualifier  instead  of  as  a  file  qualifier. 

Remember,  you  do  not  need  to  type  the  full  form  of  the  command  unless 
you  are  keeping  a  record  of  terminal  activity.  The  following  coaunand 
line  has  the  same  effect  as  the  one  above: 

DCL>MAC/NOOB  PILE/CR 
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Proa  an  MCR  ttrainal,  you  ganarat*  tha  cross-rafaranca  listing  by 
typing  tha  following: 

MCR>NAC  ,PILC/CR/-8P-PILE 

(any  arrors  causa  total  numbar  to  ba  printad) 

> 

Bacausa  no  fila  spacif ication  pracades  tha  conma  in  tha  comiand, 
NACRO-11  omits  craating  tha  objact  nodula  and  produces  only  a  listing 
fila.  Tha  /CR  dasignation  tails  tha  assemblar  to  ganarata  a  raquast 
for  tha  CRP  task  to  produca  a  cross-referanca  listing.  (Osiitting  the 
coana  froa  tha  coaaand  causes  an  error  because  the  coaaand  then 
requests  an  objact  nodule  only.  With  an  object  aodule  specification, 
tha  designations  /CR  and  /-SP  are  illegal.) 

NOTE 

If,  after  you  request  a  cross-reference 
listing,  you  discover  that  tha 
inforaation  is  aissing  fron  your 
listing,  the  CRF  task  is  either  not 
installed  on  your  system  or  still 
processing  the  request.  Ask  your  systea 
manager  to  install  the  CRP  task. 

The  CRP  task  appends  the  cross-reference  listing  to  the  end  of  the 
listing  file,  denoting  the  cross-references  by  the  titles  SYMBOL  CROSS 
RBPBREMCE  and  MACRO  CROSS  RBPERBNCE. 


3.6   SPOOLING  A  COPY  OP  LISTINGS 

Once  you  have  developed  an  error-free  asseably,  you  can  obtain  a  hard 
copy  of  tha  listing  for  reference.  Proa  a  DCL  tarainal,  type  one  of 
the  following  coaaand  lines: 

DCL>PRINT  PILE.LST 
> 

•r 

DCL>MCR  PIP  PILE.LST/SP 
> 

Tha  coaaand  lines  create  a  request  to  the  spooling  task  to  print  the 
file  you  specify.  (You  can  specify  aore  than  one  file  at  a  tiae  by 
listing  aore  than  one  file  specification  in  tha  coaaand  line, 
separating  each  with  a  coaaa.)  Your  request  is  placed  in  a  <jaaue  of 
requests. 

If  your  systea  does  not  have  spooling,  you  can  list  the  file  directly 
on  the  printer,  as  follows: 

DCL>MCR  PIP  LP: -PILE.LST 
> 

If  the  printer  is  not  busy  or  allocated  by  another  user,  PIP  outputs 
the  file  to  LPO:. 
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Th*  precaaa  for  obtaining  a  hard-copy  liatlnq  la  vary  alallar  froa  an 
MCR  tarainal. 

Proa  an  MCR  tarainal,  typa  ona  ol  tha  following  coaaand  llnaai 

MCR>PRIirT  PILI.L8T 
> 

or 

MCR>PIP  PILI.L8T/8P 
> 

Tha  coaaand  linaa  craata  a  raquaat  to  tha  apoollng  taak  to  print  tha 
flla  you  apacify.  (You  can  apacify  aora  than  ona  flla  at  a  tiaa  by 
Hating  aora  than  ona  flla  apaclf ication  in  tha  coaaand,  aaparating 
aach  wir.h  a  coaaa.)  Your  raquaat  is  placad  in  a  quaua  of  raquaata. 

If  your  aystaa  doaa  not  hava  apoollng,  you  can  Hat  tha  flla  dlractly 
on  tha  prlntar,  aa  follows: 

NCR>PIP  LPt-PILB.LST 
> 

If  tha  prlntar  la  not  busy  and  la  not  allocatad  by  anothar  uaar,  PIP 
outputa  tha  flla  to  LPO:. 


3.7   CLBAMIMG  UP  TBB  DISK  DIRECTORY 

Aftar  you  adit  and  raassaabla  tha  aourca  filaa  aavaral  tlaaa,  your 
diractory  bacoaaa  cluttarad  with  aultlpla  varaiona  of  tha  aaaa  filas. 
DCL  includaa  a  DIRBCTORV  coaaand  for  Hating  Inforaation  about  filaa. 
Tha  following  coaaand  liats  all  tha  filaa  in  your  diractory: 

DCL> DIRECTORY 

(tha  diractory  listing  appaara) 


You  will  notlca  in  tha  diractory  a  nuabar  of  filaa  with  tha  saaa  naaa 
and  typa,  but  diffarant  varsion  nuabars.  Usa  tha  following  coaaand  to 
purga  all  but  tha  aoat  racant  varalon  of  thaaa  filaa: 

DCL> PURGE  *.NAC,*.L8T,*.0BJ 

Froa  an  NCR  tarainal,  you  can  Hat  tha  naaa,  typaa,  varalon  nuabars, 
and  aisaa  of  tha  filaa  storad  in  yoi^r  UFO  by  typing  tha  following 
coaaand  Una: 

NCR>PIP  /M 

(tha  diractory  listing  appaars) 

> 

Tha  dasignatlon  /LI  causaa  PIP  to  list  tha  diractory  inforaation  at 
your  tarainal.  By  dafault,  tha  coaaand  Una  raquasts  all  naaas, 
typaa,  and  varaiona  of  filas  in  your  UFD. 
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By  •xaaining  the  directory  information,  you  notice  that  files  with  the 
same  name  and  type  have  multiple  versions.  Use  the  following  command 
line  to  the  PIP  program  to  purge  all  but  the  most  recent  version  of 
the  files: 

MCR>PIP  *.MAC,*.LST,*.OBJ/PU 
> 

The  designation  /PU  purges  all  but  the  latest  version  of  the  files 
specified.  The  asterisk  character  in  the  command  denotes  all  files 
having  any  name  and  the  type  specified. 

3.8   GUIDE  TO  FURTHER  READING 

The  sections  or  chapters  in  the  following  documents  contain  additional 
information  on  the  subjects  described  in  this  chapter. 

Document 
RSX-llM/M-PLUS  Command  Language  Manual 

Section  6.2.1,  MACRO  Command 
PDP-11  MACRO- 11  Language  Reference  Manual 

Chapter  8,  lAS/RSX-llM/RSX-llM-PLUS  Operating  Procedures 

8.1.1,  Default  Pile  Specifications 

8.1.2,  MCR  Command  String  Format 
8.1.2.1,  MCR  File  Specification  Switches 

8.1.3,  DCL  Operating  Procedures 

8.5,  MACRO-11  Erroi  Messages  Under  lAS/RSX-llM/M-PLUS 
Appendix  D,  Error  Messages 

RSX-llM/M-PLUS  Utilities  Manual 

Chapter  3,  Peripheral  Interchange  Program  (PIP) 
Appendix  B,  The  Cross-Reference  Processor  (CRF) 

RSX-llM-PLUS  Batch  and  Queue  Operations  Manual 

Chaptei;  2,  Queuing  Jobs 
Section  2.1,  PRINT  Command 
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CHAPTER  4 
BUILOIKG  AMD  TBSTIMG  A  TASK 


This  chapter  dcscribas  ways  to  us*  th«  T«sl(  Buildar  (TKB)  prograa  to 
Croat*  a  task  iaaqo  from  prograa  objoct  aodulo*.  Th*  procoduros 
doscribod  in  this  chaptor  assuaa  that  you  havo  croatod  throo 
•rror-fro*  objoct  aodulos  as  doscribod  in  Chaptor  3. 


4.1   CRBATIMG  A  TASK  IMAGE 

Tho  TKB  proqraa  croatos  a  task  iaage  filo  that  can  be  loaded  into 
■eaory.  You  can  supply  as  input  to  TKB  either  a  single  object  Module 
or  Multiple  object  Modules.  In  Most  cases,  hoirever,  your  progrsMS 
will  consist  of  Multiple  object  Modules.  The  following  sections 
describe  the  procedures  and  the  way  TKB  reports  error  conditions. 


4.1.1  Supplying  a  Single  Object  Module 

Use  the  DCL  LINK  coMMand  to  create  a  task  iMsge   file   froM  a  single 
object  Module t 

DCL>LIMK  FILE 

(any  error  Messages  appear) 


Once  again,  all  defaults  are  applied  autoMStically.  The  LINK  coMMand 
defaults  to  an  object  Module  in  a  file  nsMod  PILE. OBJ  and  causes  TKB 
to  produce  a  file  naMod  PILE.TSK  containing  the  task  iMage. 

To  perforM  the  ssMe  function  froM  an  NCR  terMinal,  enter  the  'ollowing 
coMMand  line: 

MCRyPKB  PILE-PILE 

(any  error  Messages  appear) 


The  right  side  of  the  equal  sign  specifies  the  file  containing  the 
object  Module.  TKB  assuMos  that  the  type  *n  the  file  specification  is 
02>J.  The  left  side  of  the  equal  eign  qivnr>  the  specification  of  the 
task  iMsge  file  to  tihich  TKB  assigns  the  file  type  TSK-  Agtiin,  ( t 
with  the  asseMtler,  it  is  convenient  to  apply  the  ssiae  na«v  *.o  both 
the  output  file  and  the  input  file  and  to  let  TKB  apply  th  dcfaclt 
type  specifications. 
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TKB  tries  to  resolv*  all  global  rafaranca*  in  the  object  aodula.  If 
there  are  undefined  references  after  the  module  has  been  processed, 
TKB  searches  the  systen  object  library  SYSLIB.OLB  in  UPD  [1,1]  on  the 
library  device  (LBt).  If  no  errors  are  encountered  in  the  process, 
TKB  exits  and  the  command  prompt  (>)  appears. 

If  TKB  datects  an  error  during  processing ,  it  prints  a  massage  at  ths 
terminal  in  one  of  the  following  forms  for  NCR  users t 

TKS  —  *DIAG*  -  error  message 

•r 

TKB  —  *FATAL*  -  error  message 

If  TKB  detects  an  error  during  processing,  it  prints  a  message  In  one 
of  the  following  torms  for  DCL  users: 

LINK  —  *DIAG*  -  error  message 

or 

LINK  —  *FATAL*  -  error  message 

TKB  error  messages  are  summarized  in  the  RSX-llM/M-PLUS  Task  Builder 
Manual. 

If  an  error  message  appears  and  the  error  condition  described  is  not 
operational  (for  example,  lack  of  space  for  the  task  ima«,e  file)  or  is 
not  a  fatal  error,  TKB  creates  the  task  image  file  anyway.  Depending 
on  the  error  condition,  you  may  have  to  remove  the  cause  of  the  e.^'ror 
from  the  source  file,  reassemble  the  source  file,  and  repeat  the  TKB 
procedure.  In  some  Instances,  the  diagnostic  condition  is  merely  a 
warning  and  has  no  ill  effect  when  the  task  runs.  (For  guidelines  on 
typical  error  conditions,  see  Section  4.4.) 

When  you  create  the  task  image  from  the  single  object  module  FILE. OBJ, 
TKB  prints  the  following  error  message: 

TKB  —  *DIAG*-2  Undefined  symbols  segment  FILB 

READ 
WRITE 

The  undefined  symbols  READ  and  WRITE  are  the  entry  points  of  the  two 
routines  defined  by  the  object  modules  FILEA.OBJ  and  FILEB.OBJ.  TKB 
searches  the  system  object  library  to  resolve  global  references  left 
undefined  in  your  input.  Because  TKB  failed  to  find  modules  that 
defined  these  symbols,  it  reported  the  error  condition.  (This  error 
message  is  generated  from  the  NCR  command.)  You  can  eliminate  the 
error  condition  by  following  the  procedures  described  in  the  following 
section. 


4.1.2  Supplying  Multiple  Object  Modules 

TKB  accepts  multiple  object  modules  as  input  to  the  LINK  command.  At 
a  DCL  terminal,  type  the  names  of  the  object  files,  separated  by 
commas,  as  shown: 

DCL>LINK  FILE,FILEA,FILEB 

(any  error  messages  appear) 

>        -:  ■■:-  ; 
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Th«  LINK  comnand  defaults  to  tha  flla  typa  OBJ  for  tha  thraa  input 
filas.  Tha  resulting  task  imaga  fila  is  nanad  PILE.TSK.  Tha  LINK 
command  defaults  to  tha  name  of  tha  first  object  fila  named  to  derive 
the  name  of  the  TSK  file. 

Prom  an  NCR  terminal,  specify  the  names  of  the  multiple  object  files, 
separated  by  commas,  on  the  right  side  of  the  equal  sign  in  your  TKB 
command  line,  as  shown: 

MCR>TKB  PILE-PILE, PILEA,PILEB 

(any  error  messages  appear) 


TKB  performs  the  same  actions  as  those  described  in  Section  4.1.1  for 
one  object  module  from  a  DCL  or  NCR  terminal.  Only  one  of  the  object 
modules  specified  must  have  bean  assembled  with  a  .END  directive 
giving  the  starting  address  of  the  task.  If  one  of  the  modules  does 
not  contain  the  starting  address,  TKB  assigns  the  default  transfer 
address  of  1,  which  causes  an  error  when  you  run  the  task.  See 
Section  4.4. 

TKB  can  also  accept  as  input  a  concatenated  object  module,  which  is 
merely  a  file  containing  multiple  object  modules.  To  create  a 
concatenated  file,  use  the  DCL  COPY  command,  as  shown: 

DCL>COPY 

Prom?  FILE. OBJ, PILEA,PILEB 

To?  FILCON.Orj 

> 

or 

DCL>COPY  FILE. OBJ, FILEA, FILES  FILCON.OBJ 
> 

The  response  to  the  Prom?  prompt  lists  the  files  to  be  concatenated. 
Note  that  you  need  specify  the  file  type  only  on  the  first  file 
listed.  This  type  becomes  the  default  file  type  for  subsequent  files. 
The  COPY  command  automatically  concatenates  these  files  into  a  single 
output  file. 

The  single  concatenated  object  file  can  then  be  the  sole  Input  to  the 
LINK  command,  as  shown  in  the  following  command  line: 

DCL>LINK/TASK:PILE  FILCON 

(any  error  messages  appear) 


This  operation  saves  file-processing  overhead  for  TKB.  As  a  result, 
building  a  task  from  a  concatenated  file  Is  possibly  40  percent  faster 
than  listing  the  object  modules  separately. 

Use  the  following  PIP  command  line  to  create  a  concatenated  file  from 
an  MCR  terminal: 

MCR>PIP  FILCON. OBJ-PILE. OBJ, FILEA, FILEB/ME 
> 

The  right  side  of  the  command  specifies  the  files  to  be  concatenated. 
You  need  specify  the  file  type  (OBJ)  only  on  the  first  file  because 
PIP  applies   it  as  the  default   file   type   for  subsequent  names. 
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The  designation  /MB  tells  PIP  to  nerge  (concatenate)  all  the  files 
into  the  one  file  specified  on  the  left  side  of  the  equal  sign.  (tAien 
you  supply  multiple  file  specifications  on  the  right  side  of  the 
comnand  line,  PIP  uses  /ME  as  a  default  condition.  The  command  line 
includes  /ME  merely  to  emphasize  the  concatenate,  or  merge, 
operation.) 

The  single  concatenated  object  file  can  then  be  the  sole  input  to  TKB, 
as  in  the  following  command  line: 

MCR>TKB  PILE-PILCON 

(any  error  messages  appear) 


This  operation  saves  file-processing  overhead  for  the  TKB  program  and 
is  faster  the   supplying  the  object  modules  separately. 


4.1.3  Using  the  Past  Task  Builder 

Often  you  are  performing  repetitive,  straightforward  task-building 
functions  where  speed  is  preferable  to  versatility.  In  such 
circumstances,  you  should  use  the  Fast  Task  Builder  (PTB) .  From  a  DCL 
terminal,  use  the  LINK  command  with  the  /FAST  qualifier  to  specify  the 
FTB.   Here  is  an  example: 

DCL> LINK/FAST/MAP  FILE, FILEA, FILES 
> 

To  invoke  the  FTB  from  an  MCR  terminal,  use  the  following  command t 

MCR>FTB  FILE, FILE/-SP-FILE,FILEA, FILES 
> 

FTB  runs  three  to  four  times  faster  th^n  TKB  but  is  less  versatile 
than  TKB.  For  example,  FTB  does  not  create  a  global  cross-reference 
listing  or  a  symbol  definition  file.  In  addition,  the  FTB  map  has 
less  information  than  the  TKB  map. 


4.2   TASK  BUILDER  DEFAULTS 

When  you  build  a  task  image,  TKB  applies  certain  defaui^  conditions  to 
your  program,  including  the  partition  in  which  your  task  runs,  the 
host  system  memory  management  characteristics,  the  task's 
checkpointability,  and  the  number  of  logical  units  your  task  can 
access.  If  your  program  does  not  use  the  default  conditions,  the 
process  of  building  a  task  becomes  more  complex.  You  can  consult  the 
RSX-llM/M-PLUS  Task  Builder  Manual  for  the  procedures  to  override  the 
default  conditions . 

TKB  assigns  your  program  to  be  run  in  the  default  partition,  called 
GEN.  If  you  are  building  a  task  to  run  in  another  partition,  you  can 
either  supply  the  correct  partition  name  at  run  time  or  rebuild  the 
task  and  specify  the  correct  partition  name  then. 
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TKB  applies  ■•■ory  Managanant  charactaristlcs  dapandlng  on  tha  systan 
on  which  you  build  tha  task.  If  your  systan  has  namory  aanagamant 
hardwara,  TKB  allocatas  manory  starting  at  virtual  address  0  and 
assuaias  that  tha  task  will  ba  relocated  by  nenory  management  hardware. 
Therefore,  the  task  can  be  run  in  any  partition  large  enough  to 
contain  the  image.  If  your  system  does  not  have  memory  management 
hardware,  TKB  assumes  that  the  task  runs  at  a  fixed  physical  address 
that  the  system  must  supply. 

On  RSX-llM  systems,  TKB  assumes  that  the  task  is  not  checkpointable 
and  does  not  use  the  floating-point  processor. 

On  RSX-llN-PLUS  systems,  TKB  assumes  that  the  task  is  not 
checkpointable;   however,  it  does  use  the  floating-point  processor. 

TKB  establishes  the  maximum  number  of  logical  units  (six)  the  task  can 
access  and  supplies  the  assignments  for  these  logical  units.  The 
default  assignments  are;  logical  units  1  through  4  are  assigned  to 
the  system  device  (SY:);  unit  5  is  the  task-initiating  terminal 
(TI:);  and  unit  6  is  the  console  listing  device  (CL:).  These 
defaults  mean  that  the  task  can  simultaneously  refer  to  at  most  four 
files  on  the  system  device,  one  file  on  the  task-initiating  terminal, 
and  one  file  on  the  system  console  listing  device. 


4.3   GBMERATIMG  A  NAP  AMD  A  GLOBAL  CROSS-REFERENCE  LISTIMG 

Before  you  run  the  task  and  correct  simple  errors,  you  can  produce  a 
memory  allocation  file  (called  a  map)  and  a  cross-reference  listing  of 
global  symbols.  The  map  and  global  cross-reference  file  are  useful  in 
later  stages  of  program  development  and  for  program  documentation. 


4.3.1  Requesting  a  Map  and  a  Global  Cross-Rafarence  Listing 

In  most  situations,  you  need  a  standard  map  and  a  global 
cross-reference  listing  for  debugging  a  task,,  To  create  a  map  with  a 
global  cross-reference  listing  from  a  DCL  terminal,  type  the  following 
command  line: 

DCL>LINK/CROSS_REPERENCE/MOWIDE/MOTASK  FILE, FI LEA, FILEB 
> 

The  /NOTASK  qualifier  suppresses  the  creation  of  a  task  image  file. 
You  request  a  cross-reference  listing  with  the  /CROSS_REFERENCE 
qualifier.  The  designation  /MOWIDE  reduces  the  width  of  the  listing 
from  132  columns  to  80  columns  for  display  on  a  terminal.  Since 
/CROSS  REFERENCE  implies  a  map,  you  do  not  have  to  specify  the  /MAP 
qualifier. 

If  you  wish  to  create  both  the  task  image  file  and  the  map  with  the 
cross-reference  listing  at  the  same  time,  use  the  following  command 
line: 

DCL>LINK/CROSS/MOWIDE  FILE, FILEA, FILEB 
> 

TKB  creates  both  FILE.TSK  and  FILE. NAP.  The  map  includes  a 
cross-reference  listing. 
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R«r«  la  th«  ••■•  procadur*,  ••  parforaad  fron  an  MCR  taralnali 

MCRVTRB  ,PILB/CR/-SP/-WI*riLC,PZLBA,PILBB 
> 

Tha  right  aida  of  tha  aqual  aign  ia  tha  input  objact  nodula  (or 
corcatanatad  objact  nodule  or  nultipla  objact  aodulaa)  .  Itia  laft  aida 
of  tha  aqual  aign  in  tha  conmand  lina  apaclfiaa  the  map  file  naaa,  to 
trtii  'h  TKB  appanda  tha  file  type  MAP.  The  conma  preceding  tha  nap  fila 
naaa  aupp^asaaa  tha  creation  of  tha  taak  inage  file.^ 

To  create  a  new  varaion  of  tha  taak  inage  file  when  you  requeat  the 
nap  and  global  croaa-rafarance  liating,  type  the  connand  aa  followa: 

MCR>TKB  PILE, PILB/CR/-8P/-WI-PILE,PILEA, PILES 
> 

TKB  creataa  both  filaa. 

The  deaignation  /CR  talla  TKB  to  generate  a  requeat  for  the  CRP  taak 
to  produce  a  global  croaa-raference  liating.  The  deaignation  /-WI 
raducea  the  width  of  the  liating  fron  132  colunna  to  80  colunns  for 
diaplay  on  a  terninal.  The  CRP  taak  executea  the  requeat  from  TKB  and 
appanda  the  global  aynbol  croaa-raference  liating  file  to  the  end  of 
the  map  file.  The  global  crosa-reference  in  the  nap  liating  ia 
denoted  by  the  title  GLOBAL  CROSS  REPERENCE. 

NOTE 

If,  after  you  request  a  global 
croas-reference  liating,  you  diacovar 
that  the  nap  doea  not  have  one,  the  CRP 
taak  ia  either  not  installed  on  the 
ayatam  or  atill  processing  the  request. 
Consult  the  systen  nanager  to  have  the 
CRP  task  installed. 


4.3.2  Exanining  tha  Map  at  tha  Tarninal 

Use  the  DCL  TYPE  conmand,  as  deacribed  in  Section  3.4,  to  exanine  tha 
nap  at  your  terminal.   Hare  ia  the  connand  linat 

DCL>TYPE  PI LB. MAP 

(file  appears  on  screen) 

> 

Prom  an  NCR  ternfnal,  use  the  following  PIP  command  line,  as  descrihA'^ 
in  Section  3.4,  to   exanine  the  nap  at  your  terminal: 

MCR>PIP  Tit -PILE. NAP 

(Ille  appeara  on  acraan) 

> 


1.  The  task  inage  specification  is  null  when  a  comma  appears  first  in 

the  command  line.   If  you  omit  the  comma,  TKB  treats  the  file  name  for 

the  map  as  a  task  image  and  generates  a   syntax   error  because  the 
designation  /CR/-SP  is  illegal  with  a  task  image  file. 
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Us*  th«  control  connands  CTRL/S,  CTRL/Q,   and   CTRL/0,   summarizad   In 
Table  3-1,  to  control  tha  tarminal  output. 


4.3.3  Raquastlng  a  Full  Map 

The  map  file  produced,  as  described  in  Section  4.3.1,  is  a  short  form 
of  the  map  that  contains  most  of  the  information  needed  for  debugging 
tasks.  To  generate  a  full  form  of  the  map,  use  the  following  command 
line  from  a  DCL  terminal: 

DCL>LINK/LONG/MAPirULL/CRO/SYSTEM_LIBaARY    DI'-PLAY/NOTASK    PILE, PILEA, FI LEB 
> 

The  /LONG  qualifier  Indicates  that  you  want  the  LONG  form  of  the  map, 
and  causes  TKB  to  add  a  "File  Contents"  section  to  the  map.  The  /LONG 
qualifier  implies  the  /MAP  qualifier,  but  /MAP  is  used  here  to  give 
the  map  file  for  the  name  PULL. MAP  so  that  you  can  tell  apart  the  maps 
yoi'  have  made  for  this  demonstration  session.  The  /CRO  is  the 
abbreviated  form  of  the  /CROSS  REFERENCE  qualifier.  The 
/SYSTEM_LIBRARY_DISPLAY  qualifier  (usually  abbreviated  to  /SYS)  tells 
TKB  to  Include  system  library  contributions  to  the  task  in  the  file 
contents  section  of  the  map.  (System  symbols  are  also  included  in  the 
global  cross-reference  listing.) 

To  generate  a  full  form  of  the  Map  from  an  MCR  terminal,  specify  the 
command  line  to  TKB  as  follows: 

MCR>TKB  , FULL/-SP/-SH/MA/CR-FILE, FILEA, FILEB 
> 

The  comma  without  a  task  image  file  name  indicates  you  do  not  want  TKB 
to  build  a  task.  The  name  FULL  for  the  map  file  is  used  here  to  give 
that  file  the  name  FULL. MAP  so  that  you  can  distinguish  it  from  other 
maps  you  have  created  as  part  of  these  demonstrations.  The 
designation  /-SH  indicates  that  you  do  not  wane  the  short  form  of  the 
standard  ..lap.  TKB  therefore  Includes  the  file  contents  information  in 
the  map.  The  designation  /MA  tells  TKB  to  include  system  library 
contributions  to  the  task  in  the  file  contents  section  of  the  map. 
(System  symbols  are  also  Included  In  the  global  cross-reference 
listing.) 


4.4   RUNNING  THE  TASK  AND  CORRECTING  TYPICAL  ERRORS 

luu  execute  voui  task  by  usinq  the  RUN  command  and  the  name  of  the 
task  image  file.-^  For  example: 

>RUN  FILE 

Because  tne  task  FILE  is  not  installed  on  the  system,  the  RUN  command 
searches  your  UFD  on  device  SY:  for  a  file  named  FILE.TSK.  RUN 
Installs  it  temporarily  and  runs  it  immediately.  (The  task  will  be 
automatically  removed  when  the  task  exits.) 


1.  Both  MCR  and  DCL  include  a  RUN  command,  each  of  which  has  many 
formats.  The  form  shown  in  the  example  is  perhaps  the  most  widely 
used  form  for  program  development.  This  form,  which  is  the  same  in 
MCR  and  DCL,  runs  a  task  from  a  task  image  file  in  your  UFD.  See  the 
RSX-11?VM-PLUS  MCR  Operations  Manual  or  the  RSX-llM/M-PLUS  Command 
Language  ManuaT  for  more  information  on  the  functions  of  the  RUN 
Jnd. 


commar 
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To  run  task  PILE,  th*  Bvacutlv*  tranafvrs  control  to  th«  taak 
starting,  or  tranafar,  addraaa.  If  your  taak  ancountars  an  arror 
condition,  tha  ExMcutivo  auat  dacida  Mhathar  to  abort  tha  taak. 

Errors  that  can  cauaa  tha  Exacutlva  to  abort  a  taak  ara  alcnar 
hardwara  ralatad  or  aoftwara  ralatad.  If  tlia  arror  ia  hardwara 
ralatad,  auch  aa  a  aaaiory  parity  arror  or  a  load  failura,  tha 
Bxacutiva  bagina  aborting  tha  taak.  In  contraat,  a  aynchronoua  ayataa 
trap  (8ST)  error  condition,  auch  aa  an  illagal  inatruction,  cauaaa  tha 
Bxacutiva  to  attaapt  to  tranafar  control  to  an  SST  routina.  An  88T 
routina  ia  a  routina  within  a  taak  that  aarvicaa  a  particular  typa  of 
88T  condition.  If  your  taak  dafinas  a  routina  to  sarvica  tha  typa  of 
trap,  tha  Bxacutiva  transfara  control  to  it.  If  your  taak  doas  not 
hava  tha  routina  dafinad,  tha  Bxacutiva  aborta  tha  task. 

Aborting  a  task  forcaa  an  ordarly  taraination  of  tha  taak.  Includad 
in  tha  taraination  ia  a  raquaat  for  tha  Taak  Taraination  and 
Notification  (TRTM)  to  diaplay  a  aaaaaga  on  your  tarainal.  Tha 
prograa  diaplay  includaa  tha  cauaa  of  tha  abort  and  a  list  of  tha  task 
ragiatara  and  Procaaaor  Statua  Mord  (PS).   Por  axaaplai 

14:16:26  Task   Trao   "  tarainatad 

Odd  addraaa  or  othar  trap  four 

RO-000000 

Rl-100103 

R2-147100 

R3-140130 

R4-000000 

R5-000000 

SP-001172 

PC-000003 

PS-170017 

> 

Tha  inforaation  can  halp  you  aacartain  tha  cauaa  of  tha  abort. ^  If  tha 
cauaa  of  tha  arror  ia  hardwara  ralatad,  raport  tha  occurrence  to  your 
aystaa  aanagar,  who  can  conault  tha  error-logging  data  to  find  where 
the  problea  originated.  If  the  cause  of  the  error  was  an  SST 
condition,  you  '^an  uae  the  data  diaplayed  by  TRTN  to  find  the  problea. 

The  value  of  the  prograa  counter  (PC)  (ainus  2)  shown  in  the  display 
tells  you  the  address  of  the  instruction  that  was  being  executed  whan 
the  error  was  encountered.  In  the  exaaple  shown  above,  the  PC  is  at 
an  odd  addraaa  (000003).  By  exaaining  the  task  aap,  you  can  aacartain 
that  the  PC  address  is  not  within  the  taak  code.  This  condition 
deaonstratea  one  of  the  aore  coaaon  error  conditions.  The  aain  aodule 
MIMA  source  file  PILE. MAC  does  not  define  a  taak  transfer  addreaa. 
The  .END  directive  in  a  source  file,  used  to  define  the  starting 
address  of  a  taak,  does  not  have  the  address  syabol  of  the  first 
instruction.  If  you  oait  the  starting  address  definition,  TKB 
supplies  a  default  transfer  address  of  1.  Mhen  you  run  the  taak,  it 
cauaes  an  odd  addreaa  trap  and  taralnates.  (Note  that  the  PC  has  been 
increaented  to  000003  b'scause  it  is  pointing  to  the  next  instruction 
in  the  code.)  Therefore,  you  should  ensure  that  the  source  file 
definaa  a  atarting  address  and  that  the  address  is  even  (on  a  word 
boundary) . 

To  correct  any  errora  in  your  taak,  you  aust  edit  the  source  file(s) 
concerned,  reaasaable  the  corrected  f ile(s)  ,  and  rebuild  the  task. 


1.  Tha   foraat  of   the   Inforaation  varie?   between   ^SX-llM   and 
RSX-11M-PL!JS. 
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For    •SMipl«t 

MCR>KDI    PI  M.MAC 
(00103    LINKS   READ   IN] 
(PAGB  1] 

•L      (»     .BNO 

.END  )    TELL   ASSEMBLER    END   OP   CODE 

•C   /D     ffli       /am      START/ 

.END  START  }    TELL  ASSEMBLER   END  OP   CODE 

•EX 
(BXITJ 

>MAC  PILE,PILE/-SP-PILE 

>TKB   PILE,PILE/-dP-PlLE,PILEA,PILEB 

>RriN   PILI 

ABCvBCABAB 

THE  NUK3PR  0?  A'8  IS  0004 

> 

Aftar  you  corrvct  th«  •rror*  ani  r«bulld  the  task,  you  can  run  th« 
taak  again.  Tha  task  raadb  tb«  Una  of  text  that  you  type,  counts  tha 
nuabar  of  As,  displays  the  rasult,  and  axits. 

Tha  typical  arrors  nada  in  progtamning  result  In  an  SST  condition. 
Tha  common  conditions  are  eithar  an  odd  address  or  a  neaiory  protection 
trap.  Most  of  these  errors  occur  v^hen  you  use  relative  aode 
addressing  instead  of  iaunediate  aode.   For  exaaple: 

MOV     IBUPl^RO        } 
MOV     OPPSET(RO) ,R1    ; 

Tha  iaaadiate  aode  reference  IBUPl  aoves  the  address  of  BUPl  into 
register  0.  If  you  oait  the  nuaber  sign  (•),  however,  you  incorrectly 
specify  relative  aode  addressing,  as  follo%rs: 

MOV     BUP1,R0 

MOV      OPPSET(RO) ,R1 

This  instruction  aoves  the  contents  of  BUFl  and  not  the  address  of 
BUPl  into  RO.  The  subsequent  indexed  aode  reference  generates  either 
an  odd  address  or  aeaory  protection  trap.  (Your  task  is  atteapting 
eithar  to  illegally  reference  an  odd  address  or  to  reference  a 
location  outside  task  aeaory) .  This  type  of  error  occurs  often  when 
you  are  using  systea  directives  that  require  paraaeters  as  iaaediata 
aode  references,  and  when  you  oait  the  nuaber  sign  froa  a  paraaeter 
that  aakes  the  reference  relative. 


4.5   GUIDE  TO  PURTRER  READING 

The  sections  or  chapters  in  the  following  documents  contain  additional 
information  on  the  subjects  described  in  this  chapter. 

Docuaant 

RSX-1 IM/M-PLUS  Command  Language  Manual 

Section  6.4,  Linking  the  Task 
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R8X-11H/H-PL08  fli  BulldT  Manual 

Motion   1.1,   Th«  Task  Coanand   Llna 

Sactlon   10.1,   Siritchaa 

Sactlon   11. If   Options 

Appandix  G,   Itia  Paat  Task  Bulldar    (PTB) 

Appandix   R,   Irror  Nassaqaa 

R8X-11M/W-PLU8  Utilltias  Manual 

Chaptar   3,   Pariphoral    Intarchanga  Prograa    (PIP) 
Appandix  B,   Tha  Cross-Rafaranca  Procassor    (CRP) 
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USING  DIBUGGING  AIDS 


This  chapter  introduces  thra*  debugging  aids  that  art  halpful  in  tha 
prograa  davalopnant  procass:  tha  On-Lina  Dabugging  Tool,  tha 
Postaortan  Duap,  «nd  tha  snapshot  duap. 


5.1   TRB  ON-LIMB  DEBUGGING  TOOL 

Tha  On-Lina  Dabugging  Tool  (ODT)  is  a  spacial  coda  that  you  includa  in 
your  task  iaaga  to  assist  you  during  dabugging.  ODT  givas  you 
intaractiva  control  of  task  axacution,  and  allows  you  to  sat 
breakpoints  and  to  axaaina  and  change  data  and  instructions  within  the 
■enory-resident  task.  The  ODT  Module  is  linked  into  your  tf  .*.  iaage, 
thereby  increasing  the  size  of  the  task  iaage.  Therefore,  you  reaove 
ODT  froB  your  task  when  you  finish  debugging  by  rebuilding  the  task 
and  oaitting  the  ODT  aodule. 

ODT  coaaands  differ  froa  coaaands  in  other  utility  prograns.  Host 
prograas  have  aultiple-character  coaaands  that  require  a  line 
terainator  before  they  are  executed.  ODT  coaaands,  however,  are 
single  characters  and  require  no  line  terainator.  That  is,  ODT 
interprets  input  on  a  character-per-character  basis  rather  than  on  a 
line-by-line  basis.  Therefore,  as  soon  as  you  type  a  character  that 
ODT  recognizes  as  a  coaaand,  ODT  interprets  it  and  perforas  the 
specified  function.  This  difference  in  coaaands  aeans  that  you  aust 
be  careful  when  you  are  debugging  your  task  with  ODT. 


5.1.1   Including  ODT  In  a  Task 

The  /DEBUG  qualifier  to  the  LINK  coaaand  is  used  to  include  ODT  in  a 
task.  Here  is  an  exaaplet 

DCL>LINK/DEBUG/TASK: BUG/MAP: BUG/CROSS_REPBBBHCB  PILE, PILEA,PILBB 
> 

The  /DEBUG  qualifier  specifies  that  you  want  to  include  ODT  in  the 
task.  The  /TASK: BUG  qualifier  specifies  that  you  want  the  task  iaage 
file  to  be  naaed  BUG.TSK.  The  /NAP:BUG  qualifier  specifies  that  you 
want  the  aap  to  be  naaed  BUG. MAP.  In  this  way,  you  can  tell  tha 
difference  between  the  versions  of  the  task-built  file  with  ODT  and 
without.  The  Task  Builder  (TKB)  accesses  the  file  LB:  [l,l]ODT.i;;BJ  and 
links  it  into  the  task.  The  /CROSS_RBPERENCE  qualifier  iaplies  a  /NAP 
qualifier.   An  accurate  aap  of  the  task  is  necessary  for  use  with  ODT. 
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To  Include  ODT  in  a  task  from  an  NCR  terminal,  typ*  a  connand  Una 
similar  to  the  following: 

MCR>TKB  BUG/DA, BUG/CR-PILC,FI LEA, PI LEB 
> 

The  designation  /DA  accompanying  the  task  image  file  specification 
tells  TKB  to  include  ODT.  TKB  accesses  the  file  ODT. OBJ  in  UFD  [1,1] 
on  the  library  device  and  links  it  into  the  task  BUG.  You  should 
request  a  map  of  the  task  because  an  accurate  map  is  necessary  for  use 
with  ODT. 


5.1.2  Preparing  to  Use  ODT 

Before  you  run  a  task  containing  ODT,  ensure  that  accurate  listings  of 
the  assembled  source  files  are  available.  These  listings  show  the 
offsets  into  the  modules  in  your  task.  The  map  of  the  task  and  the 
assembled  source  listings  provide  the  data  you  need  to  set  breakpoints 
and  examine  locations  within  the  task. 


5.1.3  Setting  up  the  Task 

When  you  run  a  task  containing  ODT,  ODT  gains  control,  identifies 
itself  (and  the  task  it  controls)  ,  and  prints  its  command  prompt.  The 
following  lines  show  the  sequence; 

>RUN  BUG 
ODT:TT30 

The  notation  TT30  is  the  name  that  the  system  dispatcher  assigned  to 
the  task.  Such  a  name  consists  of  the  letters  TT  followed  by  the  unit 
number  of  the  terminal  that  requested  the  task.  (The  task  shown  here 
was  run  from  terminal  number  30  (8).) 

The  underline  character  (_)  is  ODT's  prompt.  It  indicates  that  ODT  is 
ready  to  accept  commands. 


5.1.4  Relocation  Registers 

To  access  locations  within  the  task,  you  should  establish  one  or  more 
relocation  registers.  This  set  of  eight  registers,  numbered  $R0 
through  $R7,  allows  you  to  specify  locations  within  the  task  in  terms 
of  offsets  from  the  start  of  modules  in  the  task  image. 

To  establish  the  proper  addressing  using  offsets,  you  must  first 
consult  the  location  information  in  the  task  map.  On  the  map 
printout,  the  portion  titled  Memory  allocation  synopsis  contains  the 
location  information  for  each  program  section  and  for  each 
contribution  to  the  program  sections  from  different  modules.  A  sample 
of  the  relevant  portion  of  the  map  for  the  program  BUG  is  shown  in 
Example  5-1. 


5-2 


USING  DBBUGGING  AIDU 


Bxanpl*  5-1  N«Mory  Allocation  Synopsis  from  Task  BUG  Map 


N**orw  •lloci 
••etion 


»«t»l 


Tltl*      l«»nt     ril* 


.    ■LK.t«IIMiI>LCLfltCL>CON> 


MTA      t(INI>ttLCL»RCL>CON) 


•••ODTt(RM>i>«»LfRCL>0WR) 


001202 

000340 

00224. 

001202 

000122 

00012. 

ttWUk 

01 

FILCON.OSJIl 

001J24 

000110 

00072. 

TTKA» 

01 

riLCON.OtJM 

001434 

000104 

00070. 

TTMtlT 

01 

FlLCOM.OtJII 

001S42 

000144 

OOllS. 

001942 

000 IS* 

00110. 

NUMA 

01 

FILCON.OSJIl 

001720 

000004 

00004. 

TTRKAt 

01 

FILCON.OSJIl 

001724 

000004 

00004 . 

TTHaiT 

01 

FILCON.OSJIl 

001730 

00S4S4 

029SS. 

001730 

0094S4 

02tSt. 

OSTRtX 

N04 

0ST.0SJI121 

Ths  location  inforaation  for  a  progran  section  is  tha  octal  starting 
addrass  of  tha  progran  section  and  its  extant  in  bytes  (both  octal  and 
decinal  values).  For  exanple,  for  the  blank  prograa  section,  the 
starting  location  is  1202  (8)  and  the  extent  is  340  (8),  or  224  (10), 
bytes.  Under  the  prograa  section  location  inforaation  are  the  octal 
starting  addresses  and  extents  in  bytes  for  the  contributions  froa 
each  object  aodule.  For  exaaple,  the  contribution  froa  TTRBAD  in  the 
blank  prograa  section  starts  at  location  1324  and  extends  for  110  (8), 
or  72  (10) ,  bytes. 

The  following  exaaple  shows  how  to  place  the  starting  addresses  of  the 
aodules  in  relocation  registers: 

_1202;0R 
_1324jlR 
_1434;2R 
_1542j3R 
_1720;4R 
_1724;5R 

The  R  coaaands  place  the  addresses  in  relocation  registers  0  through 
5.  (The  addresses  ar«  octal)  ODT  accepts  only  octal  nuabers.)  As 
soon  as  you  type  the  R  in  the  coaaand  line,  ODT  generates  line  feed 
and  carriage  return  operations  and  prints  another  proapt.  This  action 
indicates  that  ODT  has  executed  the  coaaand  as  soon  as  it  was  typed. 
Therefore,  before  typing  the  R  (or  any  coaaand),  ensure  that  the 
coaaand  line  is  correct. 

If  you  notice  a  typographical  error  in  the  line  before  you  type  the 
coaaand  itself,  siaply  type  either  CTRL/U,  the  nuaber  8  or  9,  or  the 
DELETE  key,  as  shown  in  the  following  exaaple: 

_1272;087 

ODT  considers  the  deciaal  nuaber  8  an  illegal  character.  Ic  discards 
the  input  line,  displays  a  question  aark  (7)  to  signal  an  error,  and 
prints  the  proapt  on  a  new  line.  You  aust  retype  the  entire  line.  If 
you  do  enter  an  incorrect  address  in  the  relocation  register,  siaply 
retype  the  coaaand,  as  follows: 

_1272»0R 
_1202;0R 

ODT  stores  the  aost  recently  entered  value  in  the  register. 
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To  acc«>s  a  location  within  a  task  most  convaniantly,  you  cust  craata 
an  addrasa  nada  up  of  tha  valuas  storad  in  tha  ralocation  ragistar  and 
a  valua  showing  tha  distanca  of  tha  location  fron  tha  ralocation 
ragistar  valua. 

Tha  ralocation  raglstar  providas  tha  baaa  addrass  of  a  nodula;  tha 
location  countar  valua  supplias  an  offsat  co  tha  location  within  tha 
progran  saction  for  tha  nodula.  Tha  connand  1202;0R  places  tha 
starting  addraas  of  tha  NUHA  contribution  to  tha  blank  program  section 
in  ralocation  ragistar  0.  Location  countar  valua  20  in  th»  assambly 
listing  for  NUMA  is  20  bytas  fron  tha  start  of  tha  addrass  in 
ralocation  ragistar  0.  You  usa  tha  two  valuas  to  forn  the  addrass  of 
tha  location.  Tha  address  is  fornad  by  typing  the  nunber  of  the 
relocation  register,  a  comma  (,),  and  the  octal  offsat  value.  For 
exanpla: 

0,20 

ODT  adds  the  base  valua  in  relocation  register  0  (1202  in  this  case) 
and  the  offset  typed  after  the  conna  (20)  .  This  creates  an  effective 
address  of  1222  (8).  You  use  this  syntax  with  various  ODT  commands  to 
access  locations  within  the  task  addr'*ss  space. 


Example  5-2  shows  a  portion  of  the   assembly 
program  section  in  the  module  NUMA. 


listing   for   the   blank 


Example  5-2   Portion  of  Assembly  Listing  for  NUMA 


NUHA    COUNT  NUNBER  OF  A'S 
ROUTINE  TO  COUNT  A'S 


NACRO  N1200   e-AUO-81  12139   fASC  3 


000000 

000000 

000000 

012700 

000004 

012701 

OOOVIO 

004767 

000014 

00S702 

000016 

001436 

000020 

009001 

000022 

010267 

00002A 

000026 

122067 

000032 

001001 

000034 

00S201 

80 

000036 

81 

000036 

009302 

82 

000040 

001372 

start: 


io*t 


20«t 


.88TTL 

ROUTINE 

.P8ECT 

NOV 

•tUflfRO 

NOV 

•SIZfRl 

CALL 

READ 

T8T 

R2 

•EO 

END 

CLR 

Rl 

NOV 

R2tNUHC 

CNF8 

(R0>*fA 

•NE 

20* 

INC 

Rl 

DEC 

R2 

BNE 

10* 

I  LOAD  DUFFCR  ADM 

I  LOAD  DUrFCR  SIZE 

»  READ  FROH  TT> 

»  ANY  CHARS  IN  D'^TrCRT 

I  IF  NOME*  FINK   le 

t  INIT  •  OF  A'S  CVUMTCR 

I  DAVE  •  OF  CHA«8  TY»C» 

I  IS  CHAR  ■  AT 

I  IF  NOt  DET  NEXT  CHAR 

•  COUNT  AN  A 

I  ONE  LESS  CHAR 

I  IF  HORE,  COHPARE  NEXT 


5.1.5  Examining  Locations 

To  examine  words  within  a  module,  type  the  address  followed   by  the 
Slash  (/)  character/  as  follows: 

0,20/005001 


The  slash  character  causes  ODT  to  open  the  designated   location  as   a 
word  and  display  its  contents. 
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TO  clo««  th«  currently  op«n  location,  typo  olthor  tho  RBTURN  koy  or 
the  LINE  rCBD  key.  Th«  RETURN  key  closes  th*  location,  as  shown  in 
ths  following  oxaaplot 

_0, 20/005001  m 

COT  closss  tho  location  and  prints  its  proapt  on  a  new  lino. 

One*  you  have  oponad  a  location,  typing  th*  LINE  PEED  kay  enables  you 
to  exaaine  successive  words  in  the  task  iaage.  The  following  exaaple 
shows  the  procedure t 

0,32/001001  IT 
7,000034  /005201  O 

In  response  to  the  LINE  PEED  key,  ODT  closes  the  current  location, 
opens  the  next  sequential  location  in  the  task  iaage,  and  displays  the 
address  of  the  location,  a  space,  the  slash  character,  and  the 
contents  of  the  location.  The  slash  character  signals  that  the 
location  is  open  as  a  tford. 

NOTE 

You  can  change  the  contents  of   the 

currently  open  location  to  n  by  typing 

the  octal  nuaiber  n  before  typing   the 

RETURN  or   LINE  PEED  key.   See  Section 
5.1.7. 

To  exaaine  bytes  within  a  task  instead  of  words,  type  the  address 
followed  by  the  backslash  (\)  character,  as  follows: 

_0,32\001 

The  backslash  character  causes  ODT  to  open  the  designated  location  as 
a  byte  and  display  its  contents.  You  can  exaaine  successive  bytes  by 
typing  the  LINE  PEED  key,  after  which  ODT  closes  the  currently  open 
byte  location,  opens  the  next  sequential  byte  location,  and  displays 
its  contents.   Por  exaaple: 

32\001  V 
7,000033  \002  m 

The  backslash  character  preceding  the  contents  signals  that  the 
location  is  open  as  a  byte. 

Before  you  proceed  in  the  debugging  session,  you  should  verify  the 
relocation  register  values  by  exaaining  a  location  in  each  aodule  and 
coaparing  its  contents  with  the  values  shown  in  the  asseably  listing. 
The  following  sequence  shows  the  procedure: 

_1, 66/002403  ® 
2,72/000207  m 
~3,121\124  m 
_4,C/000000  W 
_5, 0/000000  ® 

As  you  exaaine  each  location,  coapare  the  contents  ODT  displays  with 
the  asseably  listing.  If  the  values  do  not  aatch,  either  you  have  an 
incorrect  listing  or  the  relocation  register  value  is  wrong. 
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5.1.6  8«ttin9  Braakpoints  Within  th«  Task 

To  allow  you  to  stop  (or  braak)  task  axacutlon,  ODT  providas  sight 
ragistars  callad  braakpolnt  ragistars.  Thasa  ragistars,  nuabarad  $B0 
through  $B7,  lat  you  spacify  locations  of  instructions  at  which 
axacutlon  should  stop. 

To  astablish  braakpoints  In  tha  task,  spacify  tha  location  of  tha 
instruction  with  tha  B  coiiaand  in  tha  fornat  ajnB,  as  in  tha  following 
axaaplat 

0,10;0B 
~1,74;1B 

Tha  coaaand  placas  tha  dasignatad  addrassas  in  braakpolnt  ragistars  0 
and  1. 

NOTE 

In  spaclfying  tha  addrass  of  an 
instruction,  ensura  that  tha  location  is 
tha  first  trord  of  tha  instruction. 

As  soon  as  you  typa  tha  B  in  tha  comnand  Una,  ODT  ganaratas  tha 
carriaga  raturn  and  lina  faad  oparations  and  prints  a  pronpt. 
(Changing  a  braakpolnt  ragistar  is  the  saae  as  changing  a  relocation 
register;  simply  retype  the  comnand  line  and  give  the  altered 
contents. ) 

After  setting  up  the  breakpoint  registers,  you  can  issue  the  G  (Go) 
command  to  begin  task  execution.   For  example: 

G 
?JB:0,001010 

When  you  type  the  G  command,  ODT  swaps  a  BPT  instruction  into  each 
breakpoint  location. 1  ODT  passes  control  to  the  starting  address  of 
the  task.  The  task  executes  until  it  reaches  a  BPT  Instruction,  at 
tihlch  point  ODT  regains  control.  Whan  ODT  regains  control,  the  task 
has  not  yet  executed  the  instruction  at  the  location  where  the 
breakpoint  is  set.  ODT  swaps  tha  instructions  back  into  the  locations 
at  which  breakpoints  are  set,  and  prints  a  message  giving: 

a  The  breakpoint  register  designation 

a  Tha  relocation  address  at  which  execution  stopped 

In  the  example  above,  the  message  shows  breakpoint  register  0  and  its 
contents  (offset  10  from  the  base  address  in  relocation  register  0). 


1.  The  eight  breakpoint  instruction  registers,  with  register  names  $10 
through  $17,  contain  the  actual  instructions  during  task  execution. 
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5.1.7  Changing  th«  Contents  of  Locations  with  ODT 

Mh«n  •xacutlon  stops  at  a  braakpoint,  you  can  axanlna  and  change  data 
within  tha  task  iaaga  addraas  spaca.  Whan  axacutlon  stops  at  a 
braakpoint  location,  tha  task's  genaral  raglstars  ara  storad  in  ODT 
locations  accassad  by  tha  naaias  $0  through  $7.  Tha  following  saquanca 
shows  a  way  to  display  general  registers  0,  1,  and  2> 

_$0/  001543  O) 

$1  /000120  10 

$2  /135600  m 

The  slash  (/)  character  opens  the  general  register  as  a  word  location 
and  prints  its  contents.  Typing  the  LINE  PEED  key  closes  the  current 
location  and  opans  the  next  sequential  location. 

To  change  data,  slnply  type  a  new  value  while  the  cut  rent  location  is 
open.   The  following  sequence  shows  a  way  you  can  change  register  2: 

_$2/  135600  100  Q) 

$3  /140130  m 

While  the  location  (register  2)  is  open,  you  can  type  the  new  value  to 
replace  the  current  contents.  ODT  writes  the  new  value  100  (8)  into 
the  currently  open  location  before  closing  it  and  opening  tha  next 
sequential  location. 

Any  locations  within  the  task  can  be  exanined  and  changed.  The 
following  sequence  sho%fS  a  way  to  open  a  location  as  a  byte  and  change 
its  contents: 

_3,0\101  102  m 
_3,0\102  101  m 

The  backslash  (\)  character  opens  the   specified  address  as  q  byte 

location.   The  new  value  102  (8)  is  written  to  the  open  location  as  a 

byte  value.   Typing  the  RETURN  key  closes   the   location.    The   next  •> 

coaaand   line  exanines  offset  0  to  verify  that  it  contains  102  (8)  and 

than  changes  the  contents  back  to  101. 

After  you  examine  and  change  locations,  resune  execution  with  the  P 
(Proceed)  coaaand,  as  follows: 

PABCABCABAB  m 
TB:1, 000074 

The  P  coaaand  causes  ODT  to  swap  in  the  BPT  instructions,  restore  the 
task  general  registers,  and  continue  with  the  instruction  at  which  the 
break  occurred. 

NOTE  i 

I 

ODT  does  not  supply  a  carriage  return 
and  line  feed  after  you  type  the  P. 
Therefore,  the  data  that  you  type  in 
response  to  the  READ  routine  will  follow 
the  P  on  the  saae  line. 
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lx«cutien  steps  at  th«  location  containwd  In  braakpoint  raqistar  1. 

Tha  G  comand  la  uaad  to  transfar  control  to  anothor  addraas  and 
eontinua  axacution.   For  axaaplai 

_1,76G 

ODT  tranafars  control  to  offaat  76  and  continuas  axacution  thara. 
Ittia  coaaand  purpoaaly  tranfara  control  to  tha  arror  routlna  to  show 
what  occura  whan  an  arror  ia  ancountarad.   Saa  Saction  5.I.S. 


S.1.8  Error  Conditions  and  Tarainating  Task  Ixacution 

If  tha  task  ganarataa  an  arror  condition,  tha  Bxacutlva  handlaa  tha 
procassing  as  a  aynchronous  systaa  trap  (S8T) .  Control  is  paasad  to 
ODT,  which  prints  a  aassaga  sinilar  to  tha  following  ona: 

10x2,000000 

This  nassaga  glvas  a  coda  dascrlbing  tha  raaaons  for  tha  trap  and 
talla  tha  addraas  following  tha  location  that  ganaratad  tha  trap.  In 
t^a  aassaga  abova,  10  naana  tha  lOT  Instruction.  If  you  can  discovar 
tna  causa  of  tha  trap,  aaka  tha  appropriate  changas  in  the  taak  and 
procaad.  If  you  cannot  isolate  the  cause  of  the  trap,  you  should  exit 
froa  ODT  and  start  a  new  debugging  aession. 

To  help  ascertain  the  cause  of  the  trap,  you  can  exaaine  the  task 
registers  and  stack  before  you  start  a  new  debugging  session.  Uae  the 
register  naae  —  the  dollar  aign  ($)  followed  by  the  register  nuaber 
—  to  access  the  task  registers  as  described  in  Section  5.1.7.  To 
exaaine  the  stack,  exaaine  register  6  (the  stack  pointer)  and  uae  the 
at  sign  (9)  to  open  the  location  pointed  to  by  the  stack  pointer.  For 
exaapl.t: 

S6/001200  9 
V01200  /  001216  fO 

The  slash  (/)  charracter  opens  the  stack  pointer  as  a  word  and  displays 
the  address  of  the  tsp  of  the  stack.  The  at  sign  character  (9)  takes 
the  contenta  of  the  currently  open  location  (that  is,  the  stack 
pointer)  as  the  address  of  the  next  l«^cation  to  be  opened,  opens  it, 
and  displays  its  contents,  which  is  the  top  tford  on  the  stack. 

To  exaaine  tha  stack,  type  the  LINE  FEED  key  to  open  and  display  each 
successive  word  on  the  stack.  You  can  ascertain  the  highest  address 
the  stack  can  have  by  consulting  the  line  labeled  Stack  linlts  in  the 
task  attributes  section  of  the  aap.  The  line  gives  four  numbers:  the 
low  address  of  the  stack  area,  the  high  address  of  the  stack  area,  and 
the  octal  and  deciaal  extent  of  the  stack  area.  The  high  address 
tells  you  the  last  available  location  (that  is,  the  bottoa)  of  the 
stack.  After  you  have  exaained  the  higheot  address,  you  have  looked 
at  all  the  iteaa  on  the  atack  and  can  type  the  RETURN  key  to  close  the 
last  available  location. 

To  exit  froa  the  task  by  aeans  of  ODT,  use  the  X  coaaand  as  follows: 

_X 

ODT  perforas  the  exit  task  directive  and  returns  control  to  the 
Executive. 
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5.2   rOSTMORTlM  DUMP 


Another  dabugglnq  aid  la  th«  Postaortan  Duap  (PMD) .  It  raqulraa  no 
■paclal  coda  In  your  prograa.  Tha  axaaplaa  ahow  how  to  arabla  PHD  for 
your  taak  uaing  althar  tha  /POSnORTBM  qualiflar  or  tha  /PM  qualiflar. 
Ttiaaa  qualiflara  aat  a  bit  in  tha  taak  flaq  word  that  cauaaa  a  PHD 
whanavar  tha  taak  axlta  unaxpactadly. 

To  anabla  PHD  fro*  a  DCL  tarainal,  typa  tha  following  coaaand  llnat 

DCL>LINK/NAP/POSTMORTEH  FILB,PILEA, PILBB 
> 

Proa  an  HCR  tarainal,  uaa  tha  following  command  llitai 

MCR>TKB  PILE/PM,FILE/-SP-FILE,FILEA,FILEB 
> 

Tha  /POSTHORTEM  qualiflar  in  the  LINK  coaaand  la  tha  equivalent  of  the 
/PH  In  the  TKB  coaaand  after  the  taak  laage  file  name.  In  either 
caaa,  TKB  la  inatructad  to  set  a  bit  in  the  taak  flag  word.^  (You  can 
tell  whether  a  task  includes  PHD  by  Inspecting  the  task  attributes 
section  of  the  map.  A  line  item  called  Task  attributes  will  have  the 
designation  PN.)  When  PMD  is  in  effect  for  a  task,  the  occurrence  of 
an  error  that  generates  a  aynchronous  systea  trap  (SST)  causes  the 
Executive  to  handle  the  termination  of  your  task  in  a  special 
manner. 2  instead  of  simply  aborting  the  task,  the  Executive  generates 
a  request  for  PMD  to  create  a  formatted  disk  file  showing  the  task 
image  context.  When  a  task  generates  a  synchronous  system  trap,  the 
Executive  initiates  the  normal  task  termination  procedure  (the 
printing  of  an  error  message  and  general  register  contents  at  tha 
terminal)  and  additionally  generates  the  request  for  PMD.  To  inform 
you  that  a  dump  is  in  effect,  the  Executive  causes  the  following 
message  to  appear  at  the  terminal: 

Poat  mortem  dump  will  be  generated 

PMD  receives  the  request.,  creates  h  file  in  UFD  [1,4]  on  the  library 
device,  and  generates  a  request  to  the  spooler  to  print  the  file.  The 
file  has  the  name  of  the  task  and  a  type  of  PMD.  The  print  spooler 
automatically  deletes  a  file  with  the  file  type  PMD  after  it  is 
printed. 


5.3   THE  SNAPSHOT  DUMP 

The  snapshot  dump  capability  is  a  subset  of  the  Postmortem  Dump  task 
but  requires  special  code  in  the  task.  Whereas  PMD  generates  a  dump 
of  an  entire  task,  the  snapshot  dump  can  produce  a  dump  of  only  a 
portion  of  the  task.  Also,  PMD  generates  a  dump  only  when  the  task 
terminates  abnormally,  but  the  snapshot  code  can  produce  a  dump  at  any 
place  in  the  task  execution. 


1.  You  are  not  limited  to  specify  PMD  at  the  time  you  build  the  task. 
Postmortem  dumps  can  also  be  specified  as  part  of  the  RUN,  INSTALL, 
and  ABORT  commands.  See  the  RSX-llM/M-PLUS  Command  Language  Manual  or 
the  RSX-llM/M-PLUS  MCR  OperatTons  Manual  for  more  information. 

2.  This  discussion  assumes  that  the  task  does  not  handle  synchronous 
system  traps  through  the  SVTK$  directive  and  specially  coded  routines. 
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You  Includ*  th*  n«c«ts«ry  snapshot  cod*  in  ths  task  by  aditing  th« 
sourca  flla  and  inaarting  tha  snapshot  macro  calls  whara  you  want  to 
produce  a  dunp.l  Aftar  you  raassambla  tha  modulas  containing  tha 
snapshot  calls,  rabuild  tha  task  and  subsLituta  tha  raassamblad 
■odulas.  VAian  you  usa  snapshot  macro  calls,  you  do  not  naad  any 
spacial  swltchas  or  options  for  TKB. 

When  you  run  tha  task  and  that  section  containing  tha  spacial  coda  is 
executed,  a  snapshot  dunp  is  taken.  The  special  code  generates  a 
request  for  the  PMD  task.  (No  spacial  messages  are  printed  at  tha 
terminal.)  To  hold  the  dump,  PMD  creates  a  file  with  the  name  of  tha 
task  and  a  file  type  of  PMD  in  the  UFD  that  is  tha  same  as  the  UIC 
under  which  the  task  is  running.  PMD  then  generates  a  request  for  tha 
spooling  task  to  print  and  delete  the  file. 


S.4   GUIDE  TO  FURTHER  READING 

The  sections  or  chapters  in  the  following  documents  contain  additional 
information  on  tha  subjects  described  in  this  chapter. 

Document 

RSX-llM/M-PLUS  Task  Builder  Manual 

Appendix  D,  Memory  Dumps 
Section  D.l,  Postmortem  Dumps 
Section  D.2,  Snapshot  Dumps 

IAS/RSX-11  ODT  Reference  Manual 

Section  1.2,  Linking  ODT  with  a  User  Program 

Section  1.4,  Returning  Control  to  the  Host  System 

Section  2.2.1,  Absolute  and  Relative  Addressing 

Chapter  3,  Controlling  Program  Execution 

Section  3.1,  Setting  and  Removing  Breakpoints 

Chapter  4,  Displaying  and  Altering  the  Contents  of  Locations 

Section  4.10,  Using  Different  Output  Modes 

Section  5.2.1,  Relocation  Registers 

Section  7.1,  Calculating  Relocatable  Addresses 


1.  The  snapshot  macro  calls  the  PMD  tai;k  as  described  in   an   appendix 
of  the  RSX-llM/M-PLUS  Task  Builder  Manual. 
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CHAPTER  6 
CREATING  AND  USING  PROGRAM  LIBRARIES 


This  chapter  describes  the  procedures  to  create  and  maintain  a  library 
of  macro  source  statements  and  a  library  of  object  module  subroutines. 
It  also  shows  how  to  include  in  your  task  image  the  macro  call 
definitions  and  the  object  subroutines  from  user-created  libraries. 

The  decision  about  whether  to  implement  specific  code  as  a  macro  call 
or  as  an  object  module  subroutine  is  left  to  the  designer.  In 
general,  the  difference  between  implementations  is  a  tradeoff  of 
assembly  time  versus  linking  time  and,  secondarily,  convenience  versus 
size.  Each  time  your  source  file  invokes  a  specific  macro  call,  the 
assembler  must  include  the  macro  expansion  in  the  object  module. 
However,  when  your  program  calls  an  external  subroutine,  the 
resolution  of  the  call  is  done  during  linking.  Moreover,  using  the 
macro  call  to  generate  in-line  code  is  convenient,  but  each  invocation 
of  the  call  increases  the  size  of  the  resulting  task  image.  However, 
if  your  program  calls  a  specific  external  subroutine  more  than  once, 
the  subsequent  invocations  do  not  include  that  code  in  the  task. 


6.1   CREATING  AND  USING  A  MACRO  SOURCE  LIBRARY 

The  Librarian  Utility  Program  (LBR)  creates  and  maintains  library 
files  that  can  contain  macro  definitions,  object  modules,  or  other 
elements.  DCL  users  can  invoke  LBR  functions  through  the  LIBRARY 
command.  MCR  users  can  invoke  LBR  functions  through  the  LBR  comm<^nd. 
This  section  discusses  creating  a  library  file  of  macro  def initionr. 
Such  a  file  has  the  default  type  MLB  and  contains  only  macro 
definitions. 


6.1.1  Creating  the  Macro  Library 

Here  is  how  to  create  a  macro  library  from  one  input  file  of  source 
definitions  using  the  DCL  LIBRARY/CREATE  command; 

DCL>LIBRARY/CREATE: (BLOCKS : 25, MODULES: 128) /MACRO 
Library?  USRMAC 
Module (s)?  USRMAC 
> 

or 

DCL>LIBRARY/CREATE: (BLOCKS: 25, MODULES; 128) /MACRO  USRMAC  USRMAC 
> 

The  /CREATE  qualifier  identifies  the  LBR  function  you  want  to  invoke. 
The  arguments  to  /CREATE  specify  features  of  the  library  you  are 
creating.  Because  there  is  more  than  one  argument,  they  are  enclosed 
in   parentheses  and  separated  by  commas.   The  argument  BLOCKS: 25  gives 
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th«  l«ngth  in  blocks  for  th«  library  file.  (DCL  uses  th«  dociaal 
valu*  autoaatictlly  for  all  t.IBRARy  coaaand  crguaants.)  If  you  oait 
chls  arguaant,  LBR  craataa  a  Cila  100  blocks  long  by  default.  Tha 
arguaant  MODULES:  128  indicatas  th«t  niiab<^r  of  aodula  naaa  tabla  antrlas 
to  allocata  for  this  library.  (Each  •taci'^  dafinition  in  tha  library 
raquiras  an  entry  In  tha  aoi'.ula  naaa  tabla.)  Tha  /flACRO  qualifier 
identifies  the  type  of  library  yo>:  wish  to  create.  The  default  type 
is  /OBJECT  (to  create  an  object  aodule  library). 

Tite  Library?  proapt  requests  that  you  naaa  the  library  to  be  created. 
For  aacro  libraries,  the  default  file  rype  is  MLB.  The  Modules? 
proapt  requests  you  to  naaa  the  file  or  fii.es  containing  the  aacro 
definitions.  Ttie  default  file  type  for  this  paraaeter  is  MAC.  (If 
you  do  not  naaa   file  here,  LBR  creates  an  eapty  file.) 

There  is  further  discussion  of  how  LBR  creates  a  library  included  in 
the  MCR  coaauind  description.  Here  is  the  MCR  coaaand  line  to  create  a 
aacro  library: 

MCR>LBR  U8RMAC/CRi25.til28.tMAC-U8RMAC 

9 

The  designation  /CR  tells  LBR  to  create  a  library  file.  LBR  creates 
the  library  file  USRMAC.MLB.  For  input  to  the  library  file,  LBR  uses 
the  file  or  files  specified  to  the  right  of  the  equal  sign.  In 
Bxaaple  6-1,  the  input  file  is  USRMAC.MAC. 

Bxaaple  6-1  NACRO-11  Library  Source  Definitions 

• 

)  SAVE  -  STORES  REGISTER  ON  STACK 
I 

.MACRO   SAVE t REG  f  PUSM  REG  ONTO  STACK 

NOV      REOr-(SF> 

.ENOH 
I 

I  RESTOR  -  FOPS  REGISTER  VALUE  OFF  STACK 
I 

.MACRO  RESTOR t REG 

NOV       (SF>^>REG  I  FOP  REG  OFF  STACK 

.ENDN 

.END 

Following  the  designation  /CR  in  the  command  line  are  paraaeters, 
separated  by  colons,  that  LBR  uses  to  create  the  library. 1  The  first 
paraaeter,  25  (deciaal),  gives  the  length  in  blocks  for  the  library 
file.  If  you  oait  this  parameter,  LBR  uses  100  (decimal)  blocks  as 
the  default  length.  When  creating  the  library  file,  you  can  allow  for 
soae  future  additions  to  the  library  by  making  the  size  larger  than 
necessary.  (LBR  will  expand  a  library  file  as  needed  if  you  add 
inodules  that  will  cause  the  file  to  exceed  its  original  size. 
However,  the  library  will  no  longer  be  contiguous.)  The  second 
parameter  is  blank  because  it  applies  only  to  object  libraries.  The 
third  parameter,  128  (decimal),  is  the  number  of  module  name  table 
entries  to  allocate  for  this  library.  (An  entry  in  the  module  naaa 
table  is  required  for  each  macro  definition.)  Following  the  third 
parameter  is  the  type  of  library  to  create  (MAC  for  macro  definition). 


1.  The  numeric  parameters  are  followed  by  decimal  points  to  force  LBR 
to  interpret  them  as  decimal  numbers.  If  you  omit  the  decimal  points, 
LGR  treats  the  numbers  a?  octal. 
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You  auat  ■p«r:ify  this  paran«t«r  b«eaua«  tha  dafault  la  an  objact 
library. 

In  craating  tha  Macro  library,  LBR  allocataa  tha  raquastad  aitount  of 

contlguoua   fll«  apaca.    If   aufflciant  contiguous  spaco   la  not 

availabla,  LhR  ganarataa  tha  OPEN  FAILURE  arror  and  tarninataa.  To 

hava  tha  library  craatad,  you  nuat  aithar  fraa  up  aona  apaca  on  tha 
voluaia  or  try  a  aaallar  library  alia. 

Whan  tha  library  flla  la  craatad,  LBR  attanpta  to  Inaart  Into  tha 
library  tha  nacro  deflnltlona  from  tha  Input  flla.  LBR  aaarch«a  tha 
Input  flla  for  .MACRO  directlvaa  and  .ENDM  dlractlvaa.  If  tha  macro 
daflnltlons  ara  naatad,  only  tha  outarmoat  dlractlvaa  ara  dlractly 
callabla  fron  tha  library.  Pron  aach  nacro  daflnltlon,  LBR  axtracts 
tha  nana  and  craataa  an  antry  In  tha  nodula  nana  tabla.  Tha  antry  In 
the  modula  nana  tabla  la  tha  naana  by  which  tha  aaaanblar  flnda  tha 
associated  nacro  dafin.'tion  in  the  library.  Any  coda  or  connenta 
outside  the  directives  are  dlacarded  and  all  trailing  blank  and  tab 
characters,  blank  lines,  and  connenta  are  ellninated  from  the  nacro 
text  itaelf.  (This  action,  called  squeexing,  conserves  nenory  for  tha 
assenbler  and  reduces  the  space  required  to  hold  the  nacro 
deflnltlona.)  Errors  occurring  during  tha  inaertlon  of  deflnltlona 
usually  indicate  Inproper  definitions,  such  as  a  missing  .ENDM 
directive. 


6.1.2  Uaing  the  Macro  Deflnltlona  fron  tha  Library 

Once  the  macro  definitions  are  in  tha  library,  you  need  perform  only 
three  actions  to  have  the  a8sembl9r  include  the  macro  expansions  in 
your  code. 

1.  Include  the  name  of  the  macro  in  a  .MCALL  directive   In  your 
program  source  file. 

2.  Invoke  the  macro  call  within  the  source  file. 

3.  Specify  the  name  of  the  library  file  in  the  command   line   to 
the  assembler. 

Thus,  to  invoke  the  two  macro  library  definitions  SAVE  and  RESTOR  in 
your  program,  precede  the  macro  calls  themselves  with  a  statement  such 
as  the  following: 

.MCALL   SAVE, RESTOR      ;  CALL  DEFINITIONS  FROM  USRMAC 

This  statement  should  preferably  occur  at  the  start  of  the  source 
file.  When  you  assemble  a  source  file  that  refers  to  a  library  file, 
you  must  name  both  files  in  your  DCL  MACRO  commend  line.  Here  is  an 
example: 

DCL>MACRO  USRMAC/LIBRARY,  USRTST/LIST 

The  name  of  the  macro  library  can  appear  anywhere  but  last  in  the  list 
of  input  files  and  must  be  marked  with  the  /LIBRARY  qualifier.  Tha 
next  file  named  is  the  first  source  file. 

There  is  further  discussion  of  how  LBR  creates  a  library.  Use  the 
following  MCR  command  line  to  include  a  library  in  an  assembly: 

MCR>MAC  USRTST,USRTST/-SP=USRMAC/ML,USRTST 
> 

To  the  right  of  the  equal  sign  in  the  command  line,  specify  the  name 
of  the  macro  library  and  the  designation  /ML.   The  comma  separates  the 
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■aero  library  fll*  n«M«  and  th«  aourca  fila  naaa.  Tha  daaignatlon  /ML 
Indlcataa  to  tha  aaaaablar  that  tha  fila  la  a  aacro  library.  Tha  nana 
of  tha  aacro  library  nuat  pracada  tha  aourca  fila  that  rafara  to  tha 
■aero  dafinltions. 

NOTE 

If  tha  library  apacif leatlon  follows  tha 
aourca  fila  nana  in  tha  co«aand  and  tha 
corraaponding  daflnitiona  ara  not  in  tha 
systam  macro  library  RSXMAC,  MACRO-11 
doaa  not  racogniza  tha  library  fila  and 
ganarataa  aaaambly  arrora  in  tha  llnaa 
that  contain  oalla  to  library 
dafinltions. 

To  procass  tha  macro  calla  in  tha  aourca  fila,  tha  assamblar  usaa  tha 
namaa  glvan  in  tha  .MCALL  diractiva  to  ganarata  aymbola  for  tha  macro 
symbol  tabla.^  To  axpand  tha  macro  calla  not  daflnad  in  tha  aourca 
fila,  tha  asaanblar  saarchas  tha  library  you  spaclfiad  bafora  it 
saarchas  tha  aystam  dafault  macro  library.  NACRO-11  doas  not  aaarch 
tha  systam  macro  library  for  dafinltions  that  ara  f'^und  in  tha  uaar 
library  fila. 


6.2  CREATIMG  AMD  USING  AM  OBJECT  NODULE  LIBRARY 

LBR  may  ba  usad  to  craata  a  library  fila  containing  objact  modulaa. 
Such  a  fila  has  tha  fila  typa  OLE  (objact  library)  aa  a  dafault  and 
can  contain  only  object  modulas. 


6.2.1  Craating  tha  Objact  Modula  Library 

To  craata  an  objact  modula  library,  you  must  have  a  fila  or  fllas  that 
contain  tha  objact  modulaa  to  ba  Inaartad  into  tha  library.  Th« 
following  command  creates  the  object  library  and  insarta  tha  modulaa 
PILEA.OBJ  and  FILEB.OBJ.  Here  is  the  DCL  command  to  craata  an  objact 
module  library  consisting  of  tha  objact  modules  In  PILEA.OBJ  and 
FILEB.OBJ: 

DCL>LIBRARY/CREATE : (BLOCKS : 25 ,GLOBALS : 1 28 , NODULES : 64 ) /OBJECT 
Library?  USROBJ 
Nodule(s)?  PILEA,PILEB 
> 


•t 


OCL>LIBR/CRE: (BLO:25,GLOB:128,HOD:64)/OBJ  USROBJ  PILEA, PILES 
> 


1.  If  you  omit  the  name  of  the  macro  call  from  the  .NCALL  directive, 
the  assembler  cannot  recognize  the  call  itself  in  the  code.  (A 
corresponding  entry  Is  not  in  Its  macro  symbol  table.)  It  treats  an 
unrecognized  macro  call  as  an  implicit  .WORD  directive.  If  the  macro 
name  Is  not  a  valid  symbol,  its  usage  is  flagged  as  an  undefined 
reference  by  TKB. 
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till*  /OftJBCT  qualifier  Is  not  required  becaua*  It  la  tha  default,  but 
It  la  a  good  Idea  to  Include  It.  The  default  file  type  for  an  object 
■odule  library  la  OLB.  The  default  file  type  for  the  object  aodule 
fllea  la  OBJ.  The  arguMenta  to  /CREATE  are  the  aane  as  those  used  In 
creating  a  aacro  library  with  the  addition  of  the  GLOBALS  arguaent, 
which  appllea  to  object  libraries  only.  The  GLOBALS  arguaent 
specifies  the  nunber  of  entry  point  table  slots  to  reserve.  (An  entry 
point  Is  any  global  aynbol  In  a  Module  by  which  your  progran  refera  to 
the  aaaoclated  aodule.)  If  you  do  not  aupply  a  value,  LBR  defaulta  to 
GLOBALS: 512.  If  you  aupply  a  value  of  0,  you  can  aalntaln  aodulea 
with  duplicate  entry  points  in  the  saae  library.  The  naacs  of  the 
aodules  oust  still  be  unique.  Whan  building  a  library  with  GLOBALS:0, 
you  auat  specify  the  correct  nodule  naaes  to  TKB  when  you  build  your 
taak.  See  Section  6.2.2.  A  good  estlaate  for  the  nuaber  of  GLOBALS 
la  twice  the  nuaber  of  aodulea  the  library  will  contain.  The  value 
should  be  a  aultlple  of  64.  If  not,  LBR  ralaea  the  nuaber  to  the  next 
aultlple  of  64.  Again,  all  these  nuabers  are  autoaatically  declaal 
nuabera  in  DCL. 

Here  la  the  MCR  coaaand  line: 

MCR>LBR  USROBJ/CR:25. :128. :64.>PILEA,PILEB 
> 

There  is  further  discussion  of  how  LBR  creates  an  object  aodule 
library  in  the  MCR  coaaand  description. 

The  designation  /CR  tells  LBR  to  create  a  library  file.  LBR  uses  the 
naae  preceding  /CR  as  the  name  of  the  library  and  applies  the  default 
file  type  OLB.  Following  /CR  in  the  coaaand  line  are  parameters, 
separated  by  colons,  used  in  creating  the  file.^ 

The  first  parameter,  25  (10),  gives  the  size  in  blocks  at  which  to 
create   the  library  file.   If  you  omit  the  parameter,  LBR  supplies  100 

(10)  blocks  as  the  default  size.  Vfhen  creating  the  library,  you  can 
allow  for   future  additions  by  making  the  size  larger  than  necessary. 

(LBR  will  expand  a  library  file  as  needed  if  you  add  modules  that  will 
cause  the  file  to  exceed  its  original  size.  However,  the  library  will 
no  longer  be  contiguous.) 

The  second  parameter,  128  (10),  in  the  command  gives  the  number  of 
entry  point  table  slots  to  reserve. ^  A  good  estimate  for  the  nuaber 
of  entry  points  is  twice  the  number  of  modules  the  library  will 
contain  (that  Is,  two  entry  points  per  aodule).  If  you  oait  this 
parameter,  LBR  supplies  512  (10)  as  the  default  nuaber.  If  the  value 
you  supply  is  not  an  integral  multiple  of  64  (10) ,  LBR  raises  the 
number  to  the  next  highest  multiple  of  64  (10) . 

The  third  parameter,  64  (10),  is  the  number  of  module  name  table 
entries  to  create  for  the  library.  (The  module  name  is  the  means  by 
which  LBR  refers  to  the  module  code  in  the  library.)  If  you  omit  this 
parameter  from  the  command  line,  LBR  supplies  256  (10)  as  the  default 
number.  If  the  value  you  specify  is  not  an  integral  multiple  of  64 
(10)  ,  LBR  raises  the  number  to  the  next  highest  multiple  of  64  (10) . 


1.  The  numeric  parameters  are  followed  by  decimal  points  to  force  LBR 
to  interpret  them  as  decimal  numbers.  If  you  omit  the  decimal  points, 
LBR  treats  the  numbers  as  octal. 

2.  LBR  allows  you  to  build  an  object  library  having  zero  entry  points. 
This  feature  allows  you  to  maintain  modules  with  duplicate  entry 
points  in  the  same  library.  (The  names  of  the  modules  must  still  be 
unique.)  When  using  such  a  library,  you  must  specify  the  correct 
module  name(s)  to  TKB  when  you  build  your  task.   See  Section  6.2.2. 
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Th«  last  parameter  (onlttad  fron  tha  comnand  Una  abova)  apaclflaa  tha 
typa  of  library  to  build.   LBR  supplies  OBJ  as  tha  default  type. 

In  creating  ^he  object  library  file,  LBR  allocates  the  requested 
aaount  of  contiguous  space.  You  can  estinate  the  number  of  contiguous 
blocks  that  LBR  requires  by  using  PIP.  Request  a  directory  listing  of 
all  the  files  to  be  inserted  in  the  library  and  use  the  total  number 
of  blocks  PIP  calculates.  If  sufficient  contiguous  space  is  not 
available,  LBR  generates  the  OPEN  FAILURE  error  and  terminates.  To 
have  the  library  creatao,  you  must  either  free  up  some  space  on  the 
volume  or  try  to  build  a  sraller  object  library. 

When  the  object  library  is  created ,  LBR  attempts  to  insert  into  the 
library  the  object  modules  from  the  input  file(s).  It  arranges  the 
entries  in  the  module  name  table  in  alphabetical  order  by  module  name. 
The  module  name  that  LBR  uses  is  the  one  you  specified  in  the  .TITLE 
directive  when  you  assembled  the  object  module.  The  module  names  and 
entry  points  must  be  unique. ^  LBR  finds  the  global  symbols  in  each 
object  module  and  enters  them  in  the  entry  point  table.  If  LBR  finds 
a  module  name  or  an  entry  point  that  duplicates  one  already  used,  it 
prints  an  error  message  and  stops  processing. 

If  LBR  finds  an  error,  it  does  not  insert  any  modules  in  the  library 
from  the  file  containing  the  error.  You  must  eliminate  the  error 
condition  and  insert  the  modules  from  the  corrected  file  again.  If 
LBR  does  not  find  any  errors,  it  enters  all  the  modules  in  the 
library.  To  ascertain  what  modules  were  inserted,  obtain  a  listing  of 
the  library  as  described  in  Section  6.3.3. 


6.2.2  Using  the  Object  Modules  from  the  Library 

When  the  object  modules  are  in  the  library,  you  need  perform  only  two 
actions  to  have  TKB  includa  the  routines  in  your  task. 

1.  Include  the  CALL  x  statement  in  the  calling  module  (where  x 
is  an  entry  point  to  the  called  module) .  (It  is  assumed  that 
the  called  module  has  a  global  statement  to  define  the  entry 
point. )2 

2.  Specify  the  name  of  the  library  file  and  the  names  of  the 
called  modules  in  the  command  line  to  TKB. 

Thus,  to  invoke  subroutines  from  the  library,   ensure  that   the  CALL 
statements  are  in  your  program. 


1.  If  you  suppiess  including  entry  points  in  the  library  entry  point 
table,  LBR  allows  you  to  insert,  in  the  library,  object  modules  having 
duplicate  entry  points.  This  feature  enables  you  to  maintain  slightly 
different  modules  of  the  same  general  type  in  the  same  library.  You 
select  the  correct  module  by  specifying  the  unique  module  name  to  TKB 
when  you  build  your  task.   See  Section  6.2.2. 

2.  CALL  is  a  macro  statement  that  is  a  permanent  symbol  in  the 
MACRO-11  Assembler.  It  standardizes  subroutine  calling  conventions. 
CALL  X  translates  to  JSR  PC,x  (where  x  Is  the  subroutine  entry  point) . 
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Wh«n  you  build  a  task,  ua«  a  DCL  LINK  coaaand  Una  aiallar  to  tha 
following  I 

DCL>LINK/TA8Ki8UPLIB/MAP<SUPLIB 

Pila(a)7  riLB.USROBJ/INCLUDEt (TTRBAO.TTWRIT) 

> 

•r 

DLOLINK/TAiSUPLIB/KAPtSUPLIB  FILI,  USROBJ/INCi (TTRIAD.TTWRIT) 
> 

By  including  filaspacs  as  argunants  to  the  /TASK  and  /MAP  qualifiars, 
you  causa  tha  outfilas  from  tha  LINK  comnand  to  ba  nanad  SUPLIB.T8K 
and  SUPLIB.MAP,  raspactivaly.  The  /INCLUDE  qualifier  identifies  the 
file  USROBJ.OBJ  as  an  object  library.  The  namea  appearing  in 
parentheses,  after  /INCLUDE,  are  the  naaas  of  the  nodules  to  be 
extracted  fron  the  library  and  placed  in  the  taak.  (Reiienber  that 
these  nodule  nanes  are  derived  fron  the  nanea  given  in  the  .TITLf 
directive  in  the  MACRO  source  files,  and  not  fron  the  file  fron  which 
these  nodules  were  aaaanbled.) 

This  nethod  of  specifying  an  object  library  search  is  nore  direct  and 
faster  than  the  nethod  described  in  Section  6.2.3.  If  you  are  uaing  a 
large  library,  TKB  need  only  search  the  nodule  nane  table  for  those 
object  nodules  you  specify.  The  disadvantage  is  that  you  have  the 
responsibility  to  specify  the  nanes  of  all  the  nodules  that  your  task 
requires.  If,  however,  you  are  using  a  library  with  zero  entry 
points,  the  /INCLUDE  qualifier  is  the  only  nethod  of  telling  TKB  which 
nodules  to  include  fron  that  library. 

The  following  connand  line  is  the  MCR  equivalent  for  including 
specific  object  nodules  fron  a  library  in  your  task: 

MCR>TKB  SUPLIB , SUPLIB/-SP-FI LE , USROBJ/LB : TTREAD t TTWRIT 
> 

The  designation  /LB  after  a  nane  in  the  connand  line  indicates  to  TKB 
that  the  file  is  an  object  library.  TKB  accesses  the  file  USROBJ.OLB 
in  the  UFD  that  is  the  sane  as  the  current  UIC.  The  nanes  appearing 
after  /LB  in  the  connand  line  are  the  nanes  of  the  nodules  to  be 
extracted  fron  the  library  and  placed  in  the  task.  TKB  searches  the 
nodul«  nane  table  of  the  library  for  these  modules.  (Remenber  that 
these  nodule  nanes  are  derived  fron  the  name  given  in  the  .TITLE 
directive,  and  not  fron  the  file  nanes  fron  which  the  nodulea  ware 
created.) 

Note  that  the  nodule  names  in  the  command  line  are  preceded  by  colons, 
which  are  necessary  to  distinguish  the  names  as  library  module  names. 
Placing  a  comma  before  a  name  tells  TKB  to  treat  the  name  as  an  object 
nodule  and  to  search  your  UPD  for  a  file  with  that  name  and  a  type  of 
OBJ.  That  is,  the  colon  tells  TKB  to  process  what  follows  as  an 
argument  of  /LB,  and  the  comma  tells  TKB  to  treat  what  follows  as  a 
file  name. 

This  nethod  of  specifying  an  object  library  search  is  nore  direct  and 
faster  than  the  method  described  in  Section  6.2.3.  If  you  are  using  a 
large  library,  TKB  need  search  only  the  module  n^me  table  for  those 
object  modules  you  specify.  The  disadvantage  is  that  the 
responsibility  is  yours  to  specify  the  names  of  all  the  modules  that 
your  task  requires.  In  one  situation,  this  is  the  only  method  to  use 
a  library.  If  you  are  using  a  library  with  zero  entry  points,  this  is 
the  sole  method  of  telling  TKB  which  modules  to  Include  from  that 
library. 
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6.2.3  Osln^  th«  Library  to  R«solv«  llndafln«4  Global  Syabola 

Oftan  tha  aodulaa  In  a  taak  rafar  to  global  ayabola  that  ara  daflnad 
in  othar  aodulaa.  If  tha  Modulaa  that  dafina  tha  global  ayabola 
raaida  in  a  library,  you  can  hava  TKB  aaarch  tha  library.  In  DCL,  tha 
/LIBRARY  qualifiar  on  an  input  fila  apacif ication  for  a  LINK  cowaand 
indicataa  that  tha  antira  library  ia  to  ba  aaarchad.  Tha  /LIBRARY 
qualifiar  raplacaa  tha  /INCLUDE  qualifiar.  Tha  following  axaapla 
ahowa  tha  fom  of  tha  cowaand  lina: 

DCL>LINK/TASKiLB/MAPiLB  FILE,  USROBJ/LIBRARY 
> 

Tha  /LIBRARY  qualifiar  talla  TKB  to  aaarch  tha  library  antry  point 
tablti  for  symbols  that  ara  rafarrad  to  but  not  dafinad.  Whan  TKB 
finds  a  symbol  in  tha  tabla  that  is  unraaolvad  in  tha  task,  it 
axtracts  tha  dafining  modula  and  placas  it  in  tha  task.  If  any 
symbols  ramain  unraaolvad  aftar  tha  uaar  library  aaarch,  TKB  saarchaa 
tha  system  library. 

This  method  requires  less  effort  on  your  part  than  using  the  /INCLUDE 
qualifier,  but  if  you  ara  using  a  large  library,  the  task  build  mey 
take  considerable  time. 

The  following  command  line  is  the  MCR  equivalent  for  using  the  TKB  /LB 
switch  to  search  an  entire  library: 

MCR>TKB  LB,LB/-SP-FILE,USROBJ/LB 
> 

The  designation  /LB  with  no  module  names  tells  TKB  to  search  the 
library  entry  point  table  for  symbols  that  are  referred  to  but  not 
defined.  When  TKB  finds  a  symbol  in  the  table  that  is  unresolved  In 
the  task,  it  extracts  the  defining  module  and  places  it  in  the  task. 
If  any  symbols  remain  unresolved  after  the  user  library  search,  TKB 
searches  the  system  library. 

This  method  cf  specifying  an  object  library  search  requires  less 
effort  on  your  lart  than  the  method  described  In  Section  6.2.2, 
because  TKB  searches  the  entry  point  table  to  resolve  any  global 
references  undefined  at  that  point  in  the  processing.  If  you  are 
using  a  large  library,  TKB  may  take  longer  In  searching  the  entry 
point  table  than  if  you  had  specified  the  names  of  the  modules  to 
include  in  your  task. 


6.2.4  Dual  Use  of  tha  Library 

In  certain  circumstances,  you  may  want  TKB  to  definitely  include 
specific  modules  from  the  library  and  also  to  search  the  same  library 
to  resolve  any  undefined  references  that  may  occur.  For  example,  you 
may  have  conditional  code  in  the  main  part  of  a  task  and  do  not  know 
what  global  symbols  are  referenced.  TKB  allows  you  to  specify  the  two 
forms  of  the  library  search.  In  DCL,  this  c&n  be  done  by  combining 
the  /INCLUDE  qualifier  and  /LIBRARY  qualifiers  in  the  same  command 
line: 

DCL>LINK/TASK: LBOPT/MAP: LBOPT 

Pile(s)?  FILE,  USROBJ/INCLUDErTTREAD,  USROBJ/LIBRARY 

> 

or 

DCL>LINK/TASK: LBOPT/MAP: LBOPT  FILE,  USROBJ/INC :TTREAD,  USROBJ/LIB 
> 
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Once  again,  the  argunants  to  /TASK  and  /'HAP  qualifiers  changa  tha 
naaas  of  the  associatad  output  fllaa.  Tha  /INCLUDE  qualifier  un  the 
file  specification  for  U8R0BJ.0LB  Instructs  TKB  to  extract  tne  naaed 
■odule.  Notice  that  since  only  one  Module  is  nanad,  the  parentheses 
are  unnecessary.  The  /LIBRARY  qualifier  on  the  file  specification  for 
USROBJ.OLB  tells  TKB  to  search  cnat  library  for  any  unresolved  global 
syabols.  TKB  Includes  In  the  task  any  Modules  froM  the  library  that 
are  unresolved  at  that  point  in  the  building  of  the  task.  If  any 
unresolved  syMbols  rsMsin  after  the  search  of  tha  user  library^  TKB 
searches  the  systsM  library. 

The  following  coMMand  line  shows  the  NCR  procedure  for  specifying  two 
forLS  of  library  search  to  TKB: 

MCR>TKB  LBOPT , LBOPT/-SP-PI LE , USROBJ/LB : TTREAD , USROBJ/LB 
> 

The  first  appearance  of  th«  /LB  designation  tells  TKB  to  extract  t^a 
naMed  Module.  The  second  occurrence  tells  TKB  to  search  the  library 
for  any  unresolved  global  syMbols.  TKB  includes  in  the  task  any 
Modules  froM  the  library  that  define  the  global  aysbols  that  are 
unresolved  at  that  point  in  the  building  of  thv  task.  If  any 
unresolved  syMbols  rsMsln  after  the  user  library  saa^^ch.  TKB  searches 
the  systeM  library. 


6.3   MAINTAINING  USER  LIBRARIES 

This  section  de  rlbes  three  slMple  operations  to  Maintain  a  urar 
library;  adding  Modules  to,  replacing  a  Module  in,  and  obtaining 
InforMation  about  the  library.  MCR  users  accoMplish  these  ends  with 
various  coHMands  to  LBR.  ProM  DCL,  use  the  LIBRARY/INSERT, 
LIBRARY/REPLACE,  and  LIBRARY/LIST  coMMands. 


6.3.1  Adding  Modules  to  a  Library 

Modules  can  be  added  to  a  library  with  the  LIBRARY/INSERT  coMMand. 
Herci  is  an  exaMple: 

DCL>LIBRARY/INSERT 
Library?  USRMAC.MLB 
Module(s)?  MAC1,MAC2 
> 

or 

DCL>LIBRARy/IN5ERT  USRMAC.MLB  MAC1,MAC2 
> 

Give  the  nsMe  and  type  of  the  library  in  response  to  the  Library? 
proMpt.  Give  the  naMes  of  the  files  containing  the  library  Modules  in 
response  to  the  Module(s)?  proMpt.  The  default  file  type  for  files 
containing  library  Modules  is  the  ssms  as  for  the  type  of  library  that 
you  specify. 

You  cannot  add  Modules  to  a  library  that  has  no  reMsinlng  entries  In 
the  Module  nsMc  table.  (If  you  are  creating  an  object  Module  library, 
there  Must  be  sufficient  entry  point  tabl'*  slots  as  well.)  When  Li>R 
inset ts  a  Module  in  a  library,  it  checks  to  be  sure  that  a  Module  of 
the  ssMe  naMe  does  not  currently  reside   In  the  library.    If  nuch  a 
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■odul*  is  found,  LBR  raports  an  error  and  axlta.  (For  Inaartlnq 
object  aodulas,  LBR  also  chacka  for  duplicata  antry  point  nanaa.)  To 
add  nodulas  with  duplication,  aaa  tha  diacuaalon  of  LIBRARY/REPLACE  in 
Saction  6.3.2. 

Proa  an  MCR  tarainal,  aodulas  can  ba  addad  to  a  library  with  an  LBR 
coaaand  Una  auch  aa  tha  following: 

MCR>LBR  U8RMAC.MLB/IN-NAC1,NAC2 
> 

To  add  Bodulaa  to  a  library,  spacify  tha  nana  and  typa  of  tha  library 
fila  and  tha  /IN  daalgnatlon  (Inaart)  to  tha  laft  of  tha  aqual  sign  in 
tha  LBR  coaaand  Una.  To  tha  right  of  tha  aqual  sign,  giva  tha  naaa 
of  tha  aodulaa,  saparatad  by  a  coaaa.  You  naad  not  aupply  a  fila  typa 
bacauaa  LBR  appliaa  tha  corrajt  type  as  a  default  according  to  the 
type  of  the  library  you  apeclfy. 

The  library  aust  have  a  sufficient  nuaber  of  naaa  table  entries 
available  (and,  for  object  aodulea,  entry  point  table  alots) .  Each 
global  syabol  in  an  object  aodule  requirea  an  available  entry  point 
table  slot.  A  aodule  naae  table  entry  aust  be  available  for  each 
object  aodule  and  aacro  definition  added.  When  inaerting  a  aodule, 
LBR  checka  to  ensure  that  a  module  of  the  same  naae  does  not  currently 
reside  in  the  library.  If  a  duplicate  name  Is  found,  the  program 
reports  the  duplicate  naae  and  terminates.  For  object  modules  being 
inserted,  LBR  also  checka  for  duplicate  entry  point  names.  To  add 
aodulas  with  duplication,  you  must  either  eliminate  the  duplicate 
names  or  change  the  /IN  designation  to  /RP  (replace) .  See  Section 
6.3.2. 


6.3.2  Replacing  a  Hodule  in  a  Library 

After  you  create  a  library,  a  typical  aalntenance  function  you  will 
perfora  is  changing  and  updating  modules  in  the  library.  Because  a 
module  of  the  same  name  (and,  for  object  modules,  the  same  entry 
points)  already  exists,  you  must  perform  a  replace  operation. 

In  aCi  ,   this  is  done  with  the  LIBRARY/REPLACE  coamand: 

DCL> LIBRARY/REPLACE 

Library?  USROBJ  > 

Nodule (s)?  PILRA 

Nodule  "TTREAD"  replaced 


or 


DCL> LIBRARY/REPLACE  USROBJ  PILEA 
Nodule  "TTREAD"  replaced 


This  command  line  causes  LBR  to  logically  delete  the  module  TTREAD  and 
all  associated  entry  points  for  that  naae  from  USROBJ. OLB.  LBR  then 
inserts  the  new  version  of  module  TTREAD  from  FILEA.OBJ  and  prints  a 
message.  If  a  aodule  to  be  replaced  Is  not  found  in  the  library,  LBR 
perforas  an  insertion  but  prints  no  message.   .^^  

Note  that  LIBRARY/REPLACE  causes  a  logical  deletion  and  does  not 
reclaia  the  space  occupied  by  the  module  you  replace.  To  reclaim  this 
lost  space,  you  should  occasionally  use  the  LIBRARY/CONPRESS  command. 
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Th«  following  coanand  lln*  is  th*  MCR  equivalent   for   parfornlng   the 
raplaca  operation: 

MCR>LBR  U8R0BJ/RP-PILEA 
Module  "TTREAD*  replaced 


LBR  accesses  the  library  file  USROBJ.OLB,  logically  deletes  the  nodule 
TTREAD  and  all  of  the  entry  points  for  that  name,  and  Inserts  the  new 
version  of  nodule  TTREAD  fron  the  file  PILEA.OBJ.  LBR  prints  a 
nessage  telling  'ou  the  nana  of  each  nodule  it  replaced.  If  a  module 
to  be  replaced  does  -  '>t  exist  in  the  library  file,  LBR  assumes  that 
the  nodule  is  to  be  inserted,  autonatically  inserts  it,  but  does  not 
print  the  Message. 

LBR  does  not  autonatically  reclain  the  space  occupied  by  a  nodule  that 
you  replaced.  Therefore,  to  reclain  this  lost  space,  you  should 
occasionally  run  LBR  and  conpress  the  library  file. 


€.3.3  Obtaining  Infornation  about  a  Library 

To  obtain  infornation  about  a  library  fron  a  DCL  terminal,  type  a 
LIBRARY/LIST  connand  in  the  following  format: 

DCL>LIBRARY/LIST: LBLIST/NAMES/FULL 

Library?  DD.OLB 

> 

or 

DCL>LIB/LIS:LBLI8T/MAMES/FULL  DD.OLB 
> 

This  connand  line  causes  LBR  to  access  the  library  file  DD.OLB.  The 
list  appears  in  the  file  in  your  UPD  called  LBLIST.LST.  The  qualifier 
/PULL  lists  entry  points  and  full  infornation  (size,  date  of  creation, 
and  for  object  modules,  identification) . 

To  list  the  information  on  the  terminal  Instead  of  a  file,  use  the 
LIBRARY/LIST  command  without  a  file  specification  argument  to  the 
/LIST  qualifier: 

DCL>LIBRARy/LIST/FULL  USRMAC.MLB 

(LBR  lists  information) 
> 

To  obtain  information  about  a  library  from  an  MCR  terminal,  type  a 
conmand  line  to  LBR  similar  to  the  following; 

MCR>LBR  DD.OLB, LBLIST/LE/FU/-SP 
> 

This  command  line  causes  LBR  to  access  the  library  file  DD.OLB  in  the 

default  UPD.   The  comma  separates  the   library  file  name  from  the 

listing  file  specification.  The  designations  /LE  and  /FU  tell  LBR  to 
list  entry  {Mints  and  full  information  (size,  date  of  creation,  and, 

for  object  modules,  identification)  in  the   file  LBLIST.LST  in  the 

default  UFD.  The  designation  /-SP  inhibits  automatic  spooling  of  the 
listing  to  the  line  printer. 
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To  list  information  at  th«  tarainal,  siaply  onit  tha  fila  nana  Iron 
tho  connand  lina,  as  followst 

MCR>LBR  U8RMAC.MLB/PU 

(LBR  lista  inforaation) 

> 

Bacauae  a  aacro  library  doas  not  hava  antry  pointa,  you  can  omit  tha 
/LB  doaignatlon  from  tha  cooaand  lina. 

NCR>LBR  [1,1]USROBJ.OLB,(303,10]LBLIST/LE/FU  . 

Thia  coaaand  lina  cauaoa  LBR  to  accaaa  tha  library  fila  USROBJ.OLB  in 
UFD  (1,1].  Tha  coaaa  aaparataa  tha  library  fila  naaa  froa  tha  liating 
fila  spacif ication.  Tha  daaignationa  /LE  and  /PU  tall  LBR  to  liat 
antry  pointa  and  full  inforaation  (siia,  data  of  craation,  and,  for 
objact  aodulaa,  idantif ication)  in  tha  fila  LBLIST.LST  in  UPO 
[303,10].  If  you  oait  tha  UPD  apacif ication  from  tha  liating  fila, 
LBR  craataa  tha  liating  fila  in  tha  UPD  of  tha  library. 

To  liat  inforaation  at  tha  tarainal,  aiaply  oait  tha  fila  naaa  from 
tha  coaaand  lina,  aa  fol  jtMt 

NCR>LBR  [1,1]USRMAC.MLB/PU 

Bacausa  a  aacro  library  Joaa  not  hava  antry  pointa,  you  can  omit  tha 
/LE  daaignation  froa  th<i  coaaand  lina. 


6.4   COIDB  TO  PURTHBR  READING 

Tha  aactiona  or  chaptara  in  tha  following  docuaants  contain  additional 
inforaation  on  tha  subjacta  daacribad  in  this  chaptar. 

Docuaant 

R8X-1 1M/W-PLU8  Coaaand  Languaga  Manual 

Saction  6.3,  Tha  LIBRARY  Coaaand 
RSX-llM/M-PLUS  Task  Bulldar  Manual 

Saction  10.1.16,  /LB  (Library  Pila  Switch) 

PDP-11  MACRO- 11  Languaga  Rafaranca  Manual 

Saction  7.8,  Macro  Library  Diractive:  .MCALL 
Saction  8.1.2,  NCR  Command  String  Format 
Section  8.1.2.1,  MCR  Pila  Specification  Switchea 
Section  8.1.3,  DCL  Operating  Procedures 

RSX-llM/M-PLUS  Utilities  Manual 

Chapter  10,  Librarian  Utility  Program  (LBR) 
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CHAPTER  7 
PORTRAN  IV  PROCBDURBS 


PDP-11  FORTRAN  IV  is  on*  of  ■•v«ral   high-level  languages   optionally 

available   on   RSX-llM  and  RSX-llH-PLUS  systems.  This  chapter  briei'ly 

introduces   the  product  and   sunsiarizes   its  program   development 
procedures. 


7.1   OVBRVIEW  OP  PDP-11  PORTRAN  IV 

The  PORTRAN  IV  language  processor  on  RSX-llM  and  RSX-llM-PLUS  consists 
of  the  following  elements: 

e  The  compiler  task  FOR 

e  The  DCL  FORTRAN  command 

e  The  MCH  FOR  command 

e  An  Object  Time  System  (OTS)  library 

e  An  optional  resident  library 

The  FORTRAN  IV  compiler  accepts  an  ASCII  disk  file  containing  source 
statements,  and  generates  a  disk  file  in  object  module  format  and, 
optionally,  a  listing  file  suitable  for  printing.  The  user  interface 
to  the  compiler  is  similar  to  that  of  the  MACRO-11  Assembler.  The 
program  development  procedures  are  like  those  for  assembly  language 
modules:  You  supply  the  object  file  to  the  Task  Builder  (TKB)  to 
obtain  an  executable  program. 

The  DCL  FORTRAN  command  parallels  in  function  the  DCL  MACRO  command, 
and  the  MCR  FOR  command  parallels  in  function  the  MCR  MAC  command. 
The  FORTRAN  and  FOR  commands  pass  an  ASCII  source  file  to  the  FORTRAN 
compiler,  and  the  compiler  generates  an  object  module  and,  if  desired, 
a  listing  file.  The  program  development  procedures  are  very  similar 
to  those  for  assembly  language  modules:  You  pass  the  object  module  to 
TKB  using  a  LINK  command  to  obtain  a  file  containing  an  executable 
task  image. 

The  FORTRAN  IV  Object  Time  System  (OTS)  is  a  collection  of  object 
module  subroutines  the  system  uses  as  needed  in  creating  an  executable 
program.  On  systems  with  more  than  one  high-level  language,  the  OTS 
routines  for  FORTRAN  IV  must  be  segregated  from  those  of  other 
languages.  Sometimes,  the  OTS  routines  reside  in  the  system  object 
library  SYSLIB.  Regardless  of  their  location,  however,  the  OTS 
routines  must  be  accessible  to  the  Task  Builder.  The  difference  to 
you   is  whether   the   library  containing   the  OTS  routines  must  be 
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•xpllcltly  named.  If  the  OTS  routines  ara  In  SYSLIB,  tha  Task  Buildar 
can  locata  than  without  an  explicit  spaciCication  bacausa,  as  a 
default  condition,  it  automatically  si-arches  the  system  library. 

The  FORTRAN  IV  compiler  does  not  generate  all  of  the  machine  code 
required  by  a  task  at  run  time.  Common  sequences  of  code  reside  in 
the  OTS  library.  During  compilation,  FORTRAN  IV  flags  these  common 
sequences  as  undefined  global  symbols.  The  Task  Builder  must  then 
resolve  the  undefined  references  by  selecting  from  the  OTS  those 
modules  that  resolve  the  symbols  in  the  object  module. 

In  a  narrow  sense,  the  OTS  contains  the  routines  that  the  compiler  has 
previously  designated  to  be  linked  into  your  task.  In  practice, 
however,  the  OTS  can  contain  various  routines,  callable  by  the  user, 
in  addition  to  the  routines  required  by  the  compiler-assigned 
references. 

As  an  option,  a  system  installation  can  have  a  common  area  containing 
shareable  FORTRAN  IV  OTS  routines.  This  common  area,  called  a 
resident  librtry,  contains  the  most  frequently  used  routines,  taken 
from  the  OTS  and  made  available  for  user  tasks  to  link  to  and  share  at 
run  time.  Thus,  with  a  resident  library,  the  Task  Builder  generates 
references  to  the  routines  in  the  resident  library  that  you  specify 
trhen  you  build  the  task.  The  Task  Builder  does  not  include  those 
routines  in  your  task  image.  The  routines  use  virtual  address  space 
in  the  task  but  do  not  require  additional  physical  memory  in  the  task 
image.  The  resident  library,  tailored  to  the  needs  and  requirements 
of  a  particular  system,  saves  task-build  time  and  memory  by  the  amount 
of  code  that  need  not  be  repeated  in  each  memory-resident  FORTRAN  IV 
task. 


7.2   FORTRAN  IV  PROGRAM  DEVELOPMENT  PROCEDURES 

The  proi^ram  development  procedures  for  FORTRAN  IV  are  quite  similar  to 
those  for  NACRO-11.  Therefore,  this  chapter  does  not  includ?  the 
level  of  detail  found  in  previous  chapters  of  this  manual.  To  edit  a 
FORTRAN  IV  source  file,  use  the  same  commands  you  used  to  edit  the 
MACRO-11  files  shown  in  Chapter  2.  If  you  are  using  an  editor  other 
than  EDI,  perform  the  same  operations  using  your  editor. 


7.2.1  Creating  the  Source  File 

To  create  a  sample  FORTRAN  IV  source  file,  invoke  the  editor  task  EDI 
and  use  the  fallowing  commands  to  insert  the  lines  of  code  shown  in 
Example  7-1. 

MCR>EDI  AVERAGE. FTN 

(CREATING  NEW  FILE] 

INPUT 

insert  the  lines  here  and 

type  the  RETURN  key  twice  to  exit  from 

insert  mode 

m 

*EXIT 
[EXIT] 
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B«cau*«  EDI  cannot  ins«rt  a  blank  Una  In  tha  taxt  (EDI  raquiras  at 
laaat  ona  nonprinting  charactar  auch  aa  a  apaca  or  tab  charactar;  aaa 
Cartion  2.2.1.1) >  ba  aura  to  uaa  tha  C  (conaant  lina)  in  colunn  1  of 
tha  aourca  fila  in  placa  of  tha  blank  lina*  for  raadability.  If  you 
Inaart  a  lina  with  a  apaca  or  tab  charactar  in  it,  tha  FORTRAN  IV 
coapilar  ganarataa  an  arror  bacauaa  it  axpacta  a  valid  labal  on  a 
nonblank  lina. 

You  can  uaa  tha  TAB  charactar  to  facilitata  lina  fornatting.  Tha 
FORTRAN  IV  conpilar  poaitiona  tha  charactar  following  an  initial  TAB 
charactar  to  tha  propar  colunn.  That  ia,  a  digit  following  an  initial 
TAB  ia  conaidarad  a  continuation  charactar  (column  6) ,  and  a  nondiglt 
ia  conaidarad  tha  baginning  of  tha  atatanan".  (colunn  7). 

Exanpla  7-1   FORTRAN  IV  Sanple  Sourca  Code  AVERAGE. PTN 

PROORAH  AVERAGE 
C        PROORAN  TO  COHPUTE  AVERAGE  OP  MUHBER8  ENTERED  AT  TERMINAL 
C        THE  NUMBER  '0'  INDICATES  END  OF  INPUT 
C 

TOTAL  -  0  I  INITIALIZE  ACCUHULATOR 

N  -  0  I  INITIALIZE  COUNTER 

S        N  -  N  -f  1 

URITE  (Si  10)  I  PROftPT  TO  ENTER  NUHBER 

10       FORNAT  ('  ENTER  NUNBERr  END  MITH  0') 

READ  <St20)  K  I  READ  NUHBER  FROH  TERMINAL 

20       FORMAT  110 

IF  (K  .EQ.  0)  GOTO  40    t  0  MEANS  NO  MORE  INPUT 

TOTAL  -  TOTAL  ^    K  I  COMPUTE  TOTAL  WITH  NUMBER 

GO  TO  S 
C 

C  NOU>  COMPUTE  TOTAL  BY  DIVIDING  IT  BY  THE  NUMBER  OF  TIMES 
C  THROUGH  THE  LOOP 
C 
40       TOTAL  -  TOTAL/N 

URITE  <Si50)  TOTAL       I  DISPLAY  THE  RESULT 
riO       FORMAT  ('  AVERAGE  IS  'fFlO.2) 

STOP 

END 


7.2.2   Parfoming  a  Diagnostic  Run 

To  determine  whether  ther^  are  any  syntax  or  gra-nmar  errors  in  a 
source  file,  you  can  '  > form  a  diagnostic  run  using  the  OCL  FORTRAN 
comnand  line,  as  follows 

DCL>FORTRAN/NOOBJECT    AVERAGE/LIST 

AVE RAG 

FOR  —  [AVERAG]  ERRORS:   1,  WARNINGS:   0 

> 

This  comnand  line  requests  FORTRAN  IV  to  compile  the  file  AVERAGE. FTN 
and  create  a  listing  file,  AVERAGE. LST,  but  no  object  file.  By 
default,  the  listing  file  contains  source  code  and  diagnostic  messages 
only. 
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Nh«n  you  request  a  listing  filt  In  a  compilation,  FORTRAN  IV  reports 
at  ths  tamlnal  tha  nana  of  tha  proqran  unit  balng  compiled  and  a 
summary  of  ary  errors.  To  discover  what  caused  any  errors,  you  must 
examine  the  section  of  the  listing  entitled  FORTRAN  IV  DIAGNOSTICS. 
List  the  file  on  your  terminal  with  the  DCL  TYPE  command,  as  shown: 

DCL>TYPE  AVERAGE. L8T 

(PIP  displays  listing) 


See  the  following  discussion  of  the  MCR  format  for  Information  on 
reading  the  listing  file. 

To  perform  the  diagnostic  run  from  an  MCR  terminal,  issue  the 
following  command  link: 

HCR>FOR  ,AVERAGE/-SP-AVERAGE 

AVE RAG 

FOR  —  [AVERAG]  ERRORS:   1,  WARNINGS:   0 

> 

This  command  line  requests  FORTRAN  IV  to  compile  the  file  AVERAGE. FTN, 
which  resides  in  your  UFD.  The  compiler  creates  a  listing  file, 
AVERAGE. LST,  but  no  object  module.  (The  leading  comma  in  the  command 
means  a  null  file  specification  for  the  object  file.  If  you  omit  the 
comma,  FORTRAN  IV  creates  the  object  file  but  not  the  listing  file.) 
As  a  default  condition,  the  listing  file  contains  source  code  and 
diagnostic  messages  only. 

When  you  request  a  listing  file  in  a  compilation,  FORTRAN  IV  reports 
at  the  terminal  the  name  of  the  program  unit  being  compiled  and  a 
summary  of  errors  found.  To  discover  what  caused  any  errors,  you  must 
examine  the  section  of  the  listing  entitled  FORTRAN  IV  DIAGNOSTICS. 
Display  the  listing  file  by  typing  the  following  MCR  command  line: 

MCR>PIk»  TI I -AVERAGE.  LST 

(PIP  displays  listing) 


On  a  video  display  terminal,  use  the  CTRL/S  and  CTRL/Q  commands  to 
stop  and  resume  output. 

The  following  line  appears  in  the  diagnostic  section  of  the  listing: 

IN  LINE  0008,    ERROR:    SYNTAX  ERROR 

Line  0008  refers  to  the  statem<>nt  number  0008  assigned  by  the 
co;?piler.  The  error  referred  to  is  described  in  an  appendix  of  the 
language  user's  guide.  In  the  source  code  part  of  the  listing,  line 
0008  is  shown  as  follows: 

0008     20     FORMAT  110 

The  compiler  detected  missing  parentheses  on  the  field  descriptor  in 
the  FORMAT  statement.  To  correct  the  error,  you  must  edit  the  source 
file,  as  in  the  following  example: 

MCR>EDI  AVERAGE. FTN 
[00023  LINES  »EAD  IN] 
[PAGE  11 
*L  110® 
20      FORMAT  110 
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•C  /I10/(I10)/ 

20      FORMAT  (110) 

[EXIT] 


Th«  L  command  locates  the  line  containing  the  string  110  and  prints 
the  entire  line.  The  C  command  replaces  the  string  110  with  (110)  and 
prints  the  line  so  that  you  can  verify  the  change.  The  EXIT  command 
terminates  the  editing  session  and  creates  the  new,  edited  version  of 
the  file,  olext,  you  can  use  the  edited  version  to  create  an  object 
mo'^ule. 


7.2.3  Creating  an  Object  Module 

To  create  an  object  module,  simply  omit  the  /NOOBJECT  qualifier  from 
the  DCL  command  line  you  entered  prt<viously: 

DCL>FORTRAN  AVERAGE/LIST 

AVERAG 

> 

This  command  line  requests  FORTRAN  IV  to  compile  file  AVERAGE. FTN,  and 
to  create  lisr.ing  file  AVERAGE. LST  and  object  file  AVERAGE. OBJ.  If 
FORTRAN  IV  detects  any  errors,  It  prints  a  summary  at  the  terminal 
(see  Section  7.2.1).  If  there  are  no  errors,  FORTRAN  IV  returns 
control  to  DCL,  which  prints  the  >  prompt. 

Here  is  the  same  procedure  from  an  MCR  terminal: 

MCR> FOR  AVERAGE , AVERAGE/-SP=AVERAGE 

AVERAG 

> 

This  command  line  requests  FORTRAN  IV  to  compile  file  AVERAGE. FTN,  and 
to  create  object,  file  AVERAGE. OBJ  and  listing  file  AVERAGE.  LST.  If 
FORTRAN  IV  detects  any  errors,  it  prints  a  summary  at  the  terminal  as 
described  in  Section  7.2.1.  If  there  are  no  errors,  FORTRAiJ  IV 
returns  control  to  MCR,  which  prints  the  >  prompt. 


7.2.4  Creating  a  Task  Ivage 

FORTRAN  IV  object  modules  do  not  contain  all  the  object  code  required 
at  run  time.  Therefore,  when  you  run  the  Task  Builder,  either  from 
MCR  or  with  the  DCL  LINK  command,  you  must  specify  as  input  both  the 
name  of  the  object  module  and  the  name  of  the  library  containing  the 
FORTRAN  IV  OTS  routines.  The  commands  for  both  DCL  and  MCR  users 
follow. 

DCL>LINK  AVERAGE,  LB : [ 1 , 1] FOROTS/LIBRARY 


or 


MCR> TKB  AVERAGE=AVERAGE , LB :  [ 1 , 1 ] FOROTS/LB 
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Thtts*  connand  lln«s  request  the  Task  Builder  to  resolve  any  undefined 
references  by  searching  the  library  POROTS.OLB  in  UPD  [1,1]  on  the 
system  library  device,  and  linking  compiler-designated  routines  to 
module  AVERAGE. OBJ. 1  You  can  add,  as  input  to  the  Task  Builder,  file 
names  of  any  external  object  modules  that  the  main  module  calls.  As  a 
result  of  the  command  line,  the  Task  Builder  creates  a  task  image  file 
AVERAGE. TSK.  (A  memory  allocation  file  is  not  needed.)  If  the  Task 
Builder  detects  any  errors,  it  proceeds  according  to  whether  the  error 
Is  fatal  or  diagnostic.  Refer  to  an  appendix  in  the  RSX-llM/M-PLUS 
Task  Builder  Manual  for  guidelines  on  error  processing. 

NOTE 

When  building  a  task  image,  the  library 
POROTS.OLB  may  contain  routines  that 
,  support  the  PP-11  floating  point 
processor.  If  this  is  the  case,  the 
commands  for  DCL  and  MCR  users  are  as 
follows: 

DCL> LINK/CODE :PPP  AVERAGE, LB: [1 , 1] POROTS/LIBRARY 

MCR>TKB  AVERAGE/FP-AVERAGE,LB: [1 , 1) POROTS/LB 

You  also  must  use  these  commands  when 
you  rebuild  your  task  after  debugging 
It. 

The  task  image  created  by  the  Task  Builder  has  certain  defaulc 
conditions.  The  task  AVERAGE  can  be  built  to  run  successfully  without 
having  to  override  these  default  conditions.  When  you  build  a  task 
from  a  FORTRAN  IV  module,  you  may  have  to  specify  special  switches  In 
the  command  line  or  supply  options  to  the  Task  Builder.  Refer  to  the 
language  user's  guide  for  information  regarding  Task  Builder  default 
FORTRAN  IV  conditions  and  FORTRAN-specif ic  options  and  switches.  See 
also  the  description  of  the  FORTRAN  command  in  of  the  RSX-llM/M-PLUS 
Command  Language  Manual. 


7.2.5  Running  and  Debugging  a  Task 

To  execute  the  task  AVERAGE,  type  the  following   DCL  or   MCR  command 
line: 

>RUN  AVERAGE 


1.  In  the  command  line,  the  name  shown  for  the  FORTRAN  IV  Object  Time 
System  (FOROTS)  is  only  a  convention  recommended  by  DIGITAL.  Consult 
the  system  manager  at  your  Installation  because  the  FORTRAN  IV  OTS 
routines  may  reside  in  another  library  or  In  the  system  library 
SYSLIB.  (If  the  OTS  routines  do  reside  in  SYSLIB,  you  need  not 
specify  the  name  of  the  OTS  in  the  command  line  to  the  Task  Builder 
because  the  Task  Builder  automatically  searches  the  system  library.) 
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Th«  prograa  will  than  u..  ^.^  tha  following  lines  on  your  terminal t 

ENTER  NUMBER,  END  WITk<  0 

66 

ENTER  NUMBER,  END  WITH  0 

66 

ENTER  NUMBER,  END  WITH  0 

0 

AVERAGE  IS      44.00 

TT30   —   STOP 

> 

Obvioualy  44  is  not  tha  average  o£  66  and  66;  therefore,  there  must 
be  an  error  in  the  program.  If  you  cannot  locate  the  error  by  looking 
at  the  program  listing,  you  can  attempt  to  locate  the  error  by  placing 
debugging  statements  in  the  code. 

To  add  debugging  statements  to  the  program,  simply  edit  the  source 
file  with  lines  of  code  beginning  with  D  in  column  1.  For  example, 
you  can  include  statements  to  print  values  of  variables  before  and 
after  the  loop,  as  follows: 


MCR>EDI  AVERAG.PTN 

(00023  LINES  READ  IN) 

[  PAGE 

1) 

*L  5® 

5  N  -  N  -f 

1 

*im 

Dm 

WRITE  (5,6)  N, TOTAL 

Dsm 

FORMAT  ('  *»*DEBUG  LINE  N  - 

MlO,', 

® 

*L  50(58 

(E) 

50  FORMAT 

('  AVERAGE  IS  ' ,P10.2) 

*I(E) 

D® 

WRITE  (5,51)  N 

051® 

FORMAT  (•  •**DEBUG  LINE  N  - 

MIO)  8 

® 

*EXIT(E) 

[EXIT] 

TOTAL  -  • ,F10.0)  m 


The  L  commands  locate  and  print  the  contents  of  the  lines  that  precede 
where  debugging  statements  are  to  be  placed.  The  I  commands  insert 
the  debugging  statements.  You  terminate  the  Insert  operation  by 
typing  two  successive  RETURN  keys.  After  the  inserts  are  made,  the 
EXIT  command  closes  the  file  and  terminates  EDI. 

Next,  recompile  the  module  and  request  FORTRAN  IV  to  include  the 
debugging  statements,  as  shown  in  the  following  DCL  and  MCR  command 
lines: 

DCL> FORTRAN/OBJECT :DEBUG/D_LIK  ^S/LIST: DEBUG 

File(s)?   AVERAGE 

AVERAG 

> 

or 

MCR>FOR  DEBUG, DEBUG=AVERAGE/DE 

The  compiler  generates  the  files  DEBUG. OBJ  and  DEBUG. LST.  Because  of 
the  /D_LINES  qualifier  (/DE  designation  In  the  MCR  line),  the  compiler 
includes  statements  beginning  with  D  in  column  1.  If  you  omit  this 
qualification,  the  debugging  lines  are  treated  simply  as  comment 
lines. 
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Now,  rebuild  the  task  with  debugging  linns,  using  ths  DCL  or  HCR 
connand  lines  as  shown t 

DCL>LINK  DEBUG, LB: [1,1] FOROTS/LIBRARy 

or 

NCR>TKB  DEBUG-OEBUG,LBt [1,1]F0R0TS/LB 
> 

Not*  that  this  operatior.  has  nothing  to  do  with  ODT,  which  is  a 
MACRO-11  debugging  tool. 

Run  the  task  with  the  following  DCL  or  MCR  command  line: 

>RUN  DEBUG 

***DEBUG  LINE  N  ■       1,  TOTAL  -      0. 

ENTER  NUMBER,  END  WITH  0 

66 

***DEBUG  LINE  N  -       2,  TOTAL  -      66. 

ENTER  NUMBER,  END  WITH  0 

66 

***DKBUG  LINE  N  -       3.  TOTAL  -      132. 

ENTER  NUMBER,  END  WITH  0 

0 

AVERAGE  IS       44.00 

***DEBUG  LINE  N  -       3 

TT30  ~  STOP 

> 

The  debugging  statements  enable  you  to  inspect  the  values  of 
variables.  As  you  can  see,  the  loop  counter  N  is  incremented  one 
extra  time  for  the  number  0.   The  value  N  must  be  decremented  by  1. 

To  correct  the  error,  edit  the  source  file  as  follows: 

MCR>EDI  AVERAGE. FTN 

[00027  LINES  READ  IN] 

[PAGE     1] 

*L  TOTAL/® 

40  TOTAL  "  TOTAL/N 

*C  'N • (N-1 ) • 

40  TOTAL  «  TOTAL/ (N-1) 

*EXIT® 

[EXIT] 

> 

Next,  repeat  the  compile,  link,  and  run  operations.  From  a  DCL 
terminal,  use  the  following  sequence  of  command  lines: 

DCL> FORTRAN  AVERAGE/LIST 

AVERAG 

>LINK  AVERAGE, LB: [1,1] FOROTS/LIBRARY 

>RUN  AVERAGE 

ENTER  NUMBER,  END  WITH  0 

66 

ENTER  NUMBER,  END  WITH  0 

66 

ENTER  NUMBER,  END  WITH  0 

0 

AVERAGE  IS  66.00 

TT30  —  STOP 

> 
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The  program  Is  compiled  without  the  debugging  statements.   The  output 
shows  that  the  correction  eliminated  the  error. 

Here  is  the  same  procedure  from  an  MCR  terminals 

MCR>FOR  AVERAGE , AVERAGE/-SP-AVERAGE 

AVERAG 

>TKB  AVERAGE-AVERAGE , LB : [ 1 , 1 ] FOROTS/LB 

>RUN  AVERAGE 

ENTER  NUMBER,  END  WITH  0 

66 

ENTER  NUMBER,  END  WITH  0 

66 

ENTER  NUMBER,  END  WITH  0 

0 

AVERAGE  IS    66.00 

TT30  —  STOP 

> 

The  program  is  compiled  without  the  debugging  statements.   The  output 
shows  that  the  correction  eliminated  the  error. 


7.3   GUIDE  TO  FURTHER  READING 

The  section  or  chapters  in  the  following  documents  contain   additional 
information  on  the  subjects  described  in  this  chapter. 

Docunent 

IAS,  RSX,  VAX/VMS ,  FORTRAN  IV  User's  Guide 

Section  1.3,  Using  the  Task  Builder  to  Link  FORTRAN  IV  Programs 

Section  1.6,  Debugging  a  FORTRAN  IV  Program 

Section  2.1,  FORTRAN  IV  Object  Time  System 

Section  2.2,  Object  Code 

Section  2.9,  OTS  and  Shareable  Libraries 

Appendix  C,  FORTRAN  IV  Error  Diagnostics 

RSX-llM/M-PLUS  Command  Language  Manual 

Section  6.2.3,  FORTRAN  Command 
RSX-llM/M-PLUS  Task  Builder  Manual 

Appendix  H,  Error  Messages 
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ANSLIB.OLB  (ANSI  Magnetic  Tape 

library) ,  1-11 
AP  command  (EDI),  2-17 
ABsembly, 

language,  1-4  to  1-5 

See  also  MACRO-11 
listing, 

examining  at  a  terminal, 

3-6 
formatting,  2-6 
generating,  3-4  to  3-6 
page  break,  2-6 
printing,  3-8  to  3-9 
spooling,  3-8  to  3-9 
table  of  contents,  2-6 
terminal  format,  2-6 
Asterisk  character  (*), 
EDI,  2-10 
PIP,  3-10 
At  sign  (§)  , 

ODT,  5-8 
AVERAGE. FTN  source  code,  7-3 


B  command  (ODT) ,  5-6 
Backslash  character  (\)  , 

COT,  5-5 
BEGIN  command  (EDI),  2-14 
Block  mode  (EDI) ,  1-3 
Breakpoint  register,  5-6 
Breakpoints, 

setting  in  a  task,  5-6 
Buffer, 

text,  1-3 


CHANGE  command  (EDI),  2-16, 

7-5 

CLI  (Command  Line 

Interpreter)  , 

DCL,  1-1  to  1-3 

MCR,  1-1  to  1-3 

Command  Line  Interpreter, 

See  CLI 
COPY  command  (DCL) ,  4-3 
Creating, 

macro  library,  6-1  to  6-3 
object  library,  6-4  to  6-6 
object  module, 
FORTRAN  IV,  7-5 
MACRO-11,  3-4  to  3-6 
source  file, 

FORTRAN  IV,  7-2  to  7-3 
MACRO-11,  2-12 


Creating  (Cont.) 

skeleton,  2-12 
t isk  image,  1-6,  4-1  to  4-2, 
7-5  to  7-6 
CRF  (Cross-Reference 
Processor) ,  1-8 
assembly  cross-reference, 

3-7  to  3-8 
global  cross-reference, 
4-5  to  4-6 
Cross-reference  listing, 
assembly,  3-7  to  3-8 
global,  4-5  to  4-6 
Cross-Reference  Processor, 

See  CRF 
CTRL/C  command,  1-2 
CTRL/O  command,  3-7 
CTRL/Q  command,  3-7 
CTRL/S  command,  3-7 
CTRL/u  command,  5-3 


Data  block, 

local,  2-8 
Data  storage, 

control  in  assembly 

language,  1-4  to  1-5 
directive,  1-4  to  1-5 
MACRO-11  definition,  2-8 
program  section,  2-8 
DCL  (DIGITAL  Command 

Language) ,  1-1  to  1-3 
Debugging , 

introduction,  1-6  to  1-7 
MACRO-11  source  file, 

3-3  to  3-4 
task,  4-9,  5-1  to  5-2, 

7-7  to  7-9 
tool , 

See  ODT 
using  map,  5-2,  5-8 
DEC  Standard  Editor, 

See  EDT 
Default, 
file  type, 

MACRO-11,  3-5 
TKB,  4-1 
system  library  search, 

MACRO-11,  1-5,  1-10,  2-7 
TKB,  1-11,  4-2 
transfer  (starting)  address, 
4-8 
Delimiter,  2-16 
Diagnostic  run, 

FORTRAN  IV  source  file, 
7-3  to  7-4 


Index-1 


INDEX 


3-10 

(DCL) ,  3-9 


Diagnostic  run  (Cont.) 

MACRO-11  source  file, 
3-1  to  3-2 
DIGITAL  Command  Language, 

See  DCL 
Directive,  | 

assembler,  1-5 

system,  1-9  to  1-10 

use,  2-3,  2-5  to  2-6 
Directc-y, 

listing,  3-9 

purging,  3-9  to 
DIRECTORY  command 
Disk, 

private,  1-12 

public,  1-12 
Dollar  sign  ($) , 

ODT,  5-6  to  5-8 
DP  command  (EDI) ,  2-17 
Dump, 

See  PMD 


EDI,  1-3  to  1-4 
abbreviating , 

strings,  2-16 
altering, 

text,  2-16,  7-5 
AP  command,  2-17 
asterisk  (*) ,  2-10 
BEGIN  command,  2-14 
block  mode,  1-3 
CHANGE  command,  2-16,  7-5 
commands,  2-12  to  2-18 
correcting , 

source  file  error, 
7-4  to  7-5 

task  error,  4-9,  7-9 
creating, 

file,  2-9  to  2-10,  2-12, 
7-2  to  7-3 
deleting, 

characters,  2-17 

lines,  2-17 
displaying, 

text,  2-13 
DP  command,  2-17 
ellipsis,  2-16 
END  command,  2-14 
ESCAPE  key,  2-13 
EXIT  command, 

closing  file,  2-10,  7-7 

creating  new  file,  2-12, 
2-18,  7-5 
input, 

initial,  2-9.  7-3 

terminating,  2-10 


EDI  (Cont.) 

INSERT  command, 
insert  mode,  2- 
inserting, 

characters,  2 

lines,  2-9,  2 

LIST  command,  2 

LOCATE  command , 

7-4  to  7-5, 

locating , 

text,  2-14  to 
7-4  to  7- 
PLOCATE  command 
positioning , 

line  pointer, 
RENEW  command, 
RETURN  key,  2-9 
2-13,  2-18, 
slash  character 
TYPE  command,  2 
2-17 
Editor, 

text,  1-3  to  1- 
See  also  EDI, 
EDT,  1-3 
Ellipsis, 

EDI,  ?-16 
END  command  (EDI) 
.END  directive,  2 

4-8 
Entry  point,  6-5 
table,  6-5,  6-9 
zero  entry  po 
Error  message, 
FORTRAN  IV,  7-4 
MACRO-11,  3-5 
ODT,  5-3 
TKB,  4-2 
TKTN,  4-8 
ESCAPE  key, 
EDI,  2-13 
Executive, 

library,  l-ll 

macro,  1-9  to 

EXELIB.OLB  (Execu 

library),  1-1 

EXEMC.MLB  (Execut 

library),  1-9 

EXIT  command  (EDI 

2-12,  2-18,  7 

EXIT$S  directive. 


2-18, 

7- 

-7 

18 

-17 

-18 

-13 

2-14, 

2- 

-18, 

7-7 

2-15, 

5 

,    2-15 

2-14 

to 

2-15 

2-15 

to    2- 

10 

t 

7-7 

(/), 

2- 

16 

-13    to 

2 

-14, 

EDT 


,  2-14 

-7,  3-4,  4-3, 

to  6-6 

to  6-10 
ints,  6-7 


1-10 
tive 
1 
ive  macro 

to  1-10 
),  2-10, 
-5,  7-7 

2-7 


F4P0TS.0LB  (FORTRAN  IV  and 

FORTRAN  tV-PLUS  library), 
1-11 

Fast  Task  Builder, 
See  FTB 


• 
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File, 

creating, 

source,  2-9  to  2-10 
directory  listing,  3-9 
editing, 

source,  2-9,  2-12  to  2-18 
listing,  3-6 
printing,  3-8  to  3-9 
purging,  3-9  to  3-iO 
spooling,  1-8,  3-8  to  3-9 
File  type, 

.FTN,  7-3  to  7-4 
.LST,  3-4,  6-11,  7-3  to  7-4 
.MAC,  3-1 
.MAP,  4-6 
.MLB,  6-1 
.OBJ,  3-4,  7-5 
.OIB,  6-4 
.PMD,  5-10 
.TSK,  4-1 
FILEA.MAC  source  code, 

2-21  to  2-22 
FILEB.MAC  source  code, 

2-23  to  2-24 
FILE. MAC  source  code, 

2  19  to  2-20 
FOR  command  (MCR) ,  7-1,  7-4 
FOR  compiler  task,  7-1 

creating  object  module,  7-5 

/DE,  7-7 

debugging  statements,  7-7 

diagnostic  run,  7-3  to  7-4 

/D_LINES,  1-1 

FOR  command  (MCR),  7-1,  7-4 

FORTRAN  command  (DCL) ,  7-1 , 

7-3 
.FTN  file  type,  7-3  to  7-4 
/LIST,  7-3,  7-7 
/NOOBJECT,  7-3 
/OBJECT,  7-3,  7-7 
Format, 

FORTRAN  IV, 

statement,  7-3 
MACRO-11, 

source  file,  2-1  to  2-3 

skeleton,  2-4 
statement,  2-3 
FOROTS.OLB  (FORTRAN  IV  and 

FORTR\N  IV~PLUS  library), 
1-11 
FORTRAN  command  (DCL),  7-1, 

7-3 
FORTRAN  IV, 

See  also  FOR  compiler  task 
compiler  task,  7-1 
formatting  source 

statements,  7-3 
library,  1-11 


FORTRAN  IV  (Cont.) 
source  file, 
blank  file,  7-3 
coiranent  file,  7-3 
specifying  OTS  to  TKB,  7-5 
FORTRAN  IV-PLUS, 
library,  1-11 
FTB  (Fast  Task  Builder) ,  4-4 
.FTN  file  type,  7-3  to  7-4 
See  also  FOR  compiler  task 


G  command  (ODT) ,  5-6,  5-8 
Global  cross-reference, 

listing,  4-5  to  4-6 
Global  default, 

disabling  in  MACRO-11, 
3-1  to  3-2 
Global  symbol,  1-4  to  1-5 
entry  point,  1-4, 

6-5  to  6-6,  6-10 
resolution,  4-2,  6-8  to  6-9 
using  library  to  resolve 
undefined,  6-8  to  6-9 


Hardware, 

program  development,  1-12 


.IDENT  directive,  2-5 
INSERT  command  (EDI),  2-18, 

7-7        ,   . 
Inserting, 

characters  in  a  line,  2-17 
code  in  the  source  file, 

2-18 
lines  in  a  file,  2-9,  2-18 
modules  In   a  library, 
6-9  to  6-10 


Language, 

assembly,  1-4  to  1-5 
See  also  MACRO-11 
LBR  command  (MCR),  1-9,  6-2 

See  also  LBR 
LBR  (Librarian  Utility 
Program) ,  1-9 
adding  a  module  to  a 

library,  6-9  to  6-10 
/COMPRESS,  6-10 
/CR,  6-2,  6-5 
/CREATE,  6-1,  6-4  to  6-5 
efficiency,  1-9 
/FU,  6-11  to  6-12 
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LBR  (Librarian  Utility 
Program)  (Cont.) 
/FULL,  6-11 
/IN,  6-10 
/INSERT,  6-9 

LBR  command  (MCR) ,  1-9,  6-2 
/LE,  6-11  to  6-12 
LIBRARY  command  (DCL) ,  1-9, 

6-1 
/LIST,  6-9,  6-11 
listing  information, 

6-11  to  6-12 
/MACRO,  6-1  to  6-2 
macro  library,  6-1  to  6-3 
/NAMES,  6-11 

/OBJECT,  6-2,  6-4  to  6-5 
object  module  library, 

6-4  to  6-6 
.OLB  file  type,  6-4 
/REPLACE,  6-   to  6-10 
replacing  a  module  in  a 

library,  6-10  to  6-11 
/RP,  6-10  to  6-11 
/-SP,  6-11 
Librarian  Utility  Program, 

See  LBR 
Library, 

See  also  Macro,  Object,  OTS 
default  search  of  system, 

TKB,  4-2 
DIGITAL-supplied,  1-9 
macro,  6-1  to  6-3 
maintenance,  6-10  to  6-11 
object,  6-4  to  6-6 
designating  in  TKB, 

6-6  to  6-9 
system,  1-11 

using  to  resolve  undefined 
global  symbols, 
6-8  to  6-9 
obtaining  information  about 

a  user,  6-11  to  6-12 
OTS,  7-2 
search, 

MACRO-11,  1-5,  1-10,  2-7 
TKB,  1-11 
squeezing,  6-3 
system, 

macro  (RSXMAC.SML) ,  1-5 
LIBRARY  command  (DCL) ,  1-9, 
6-1 
See  also  LBR 
LINE  FEED  key, 

closing  location  (ODT) ,  5-5, 

5-7 
displaying  word  on  stack 

(ODT) ,  5-8 
opening  location  (ODT) ,  5-5, 
5-7 


Line  Text  Editor, 

See  EDI 
LINK  command  (DCL),  1-5,  4-1, 
5-1,  5-9,  6-7 

See  also  TKB 
LIST  Command  (EDI),  2-13 
.LIST  TTM  directive,  2-6 
Listing, 

assembly,  3-4  to  3-5 

control,  1-4  to  1-5,  2-6 

directory,  3-9 

examining  at  a  terminal, 
3-6,  7-4 

FORTRAN  IV,  7-5 

global  cross-reference, 
4-5  to  4-6 

printing,  3-8  to  3-9 

spooling,  3-8  to  3-9 

use  in  debugging,  5-4 
Local  data  block,  2-8 
Local  macro,  2-8 

definitions,  2-8 
Local  symbol,  1-4  to  1-5 

definitions,  2-7  to  2-8 
LOCATE  command  (EDI),  2-14, 

2-18,  7-1  to  7-5,  7-7 
Location  counter,  1-4  to  1-5 

use  in  debugging,  5-3  to  5-4 
Logical  unit  number. 

See  LUN 
.LST  file  type,  3-4,  6-11, 

7-3  to  7-4 
LUN  (Logical  unit  number), 

default  by  TKB,  4-4  to  4-5 


MAC  command  (MCR),  1-4,  3-1, 
3-5;  6-3 
See  also  MACRO-11 
.MAC  file  type,  3-1 
MAC  task,  1-4 

See  MACRO-11 
Macro, 
call , 

cross-reference  of 

symbols,  3-7  to  3-8 
resolution,  1-4,  1-10,  2-7 
unrecognized,  2-7 
library,  6-1  to  6-3 
adding  modules, 
6-9  to  6-10 
.;:'eating  a  user, 
;v        6-1  to  6-3 

definitions,  6-3  to  6-4 
DIGITAL-supplied,  1-9 
listing  information, 

6-11  to  6-12 
replacing  modules, 
6-10  to  6-11 
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Macro  (Cont.) 

search  of  system,  1-5, 
1-10,  2-7 
nymbol , 

definition,  1-4,  1-10, 
2-7,  6-4 
MACRO  command  (DCk',)  ,  1-4,  3-1, 
3-4,  6-3 
See  also  MACRO-11 
MACRO-11,  1-5 

assembling  source  file, 

3-1  to  3-2 
/CR,  1-8,  3-8 

/CROSSREFERENCE,  1-8,  3-7 
cross-reference  listing, 
1-5,  1-7,  3-7  to  3-8 
data  storage, 

definition,  2-8 
default  search  of  system 
library  1-5,  1-10, 
2-7 
defining  local  symbols, 

2-7  to  2-8 
directives,  1-4  to  1-5 
/DISABLE tGLOBAL,  3-1 
disabling  global  default,    < 

3-1  to  3-2 
/DS:GBL,  3-1 
error,  3-2  to  3-4 
error  code, 

A,  3-2  to  3-3        ^ 
E,  - 
Q,  3-4 
U,  3-3 
error  message,  3-2,  3-5 
/LIBRARY,  6-3 

/LIST,  3-1,  3-4  to  3-5,  3-7 
listing,  3-4  to  3-5 

generation,  3-6 
location  counter,  1-4  to  1-5 
MAC  command  (MCR) ,  1-4,  3-1, 

3-5,  6-3 
macro, 

cross-reference,  .  , 

3-7  to  3-8 
library  usage,  6-3  to  6-4 
symbol,  1-4,  2-7,  6-4 
MACRO  command  (DCL) ,  1-4, 

3-1,  3-4,  6-3 
/ML,  6-3  to  6-1 
/NOOBJECT,  3-1 
/OBJECT,  3-4 

object  module,  3-4  t'>  3-6 
source  file,  2-2 
Coroiat,  2-1  to  2-3 
skeleton,  2-4 
source  input,  1-4 
/-SP,  3-5,  3-8 
statement  format,  2-3 


MACRO-11  (Cont.) 
symbol , 

cross-reference, 

3-7  to  3-8 
evaluation,  1-4, 

3-1  to  3-2,  6-4 
table  of  contents 
generation,  2-6 
Map, 

debugging  use,  5-2,  5-8 
examining  at  terminal,  4-6 
full,  4-7 

generating,  4-5  to  4-7 
reducing  width,  4-5  to  4-6 
stack  limits,  5-8 
standard,  4-5  to  4-6 
.MAP  file  type,  4-6 
.MCALL  directive,  1-10, 
2-6  to  2-7,  3-3 
using  with  user  macro 
library,  6-3  to  6-4 
MCR  (Monitor  Console  Routine) , 

1-1  to  1-3 
Memory  allocation  file. 

See  Map 
.MLB  file  type,  6-1 
Module  name,  2-3,  2-5, 
6-5  to  6-7 
table,  6-9  to  6-10 

macro  library,  6-2  to  6-3 
object  library,  6-5,  6-7 
Module  version,  2-5 
Monitor  Console  Routine, 
See  MCR 


.NLIST  BEX  directive,  2-6 


.OBJ  file  type,  3-4,  7-5 
Object, 
library, 

adding  modules, 

6-9  to  6-10 
creating  't  user, 

6-4  to  6-6 
default  search  of  system, 

1-11,  4-2 
DIGITAL-suppl ied , 

1-10  to  1-11 
dual  use,  6-8  to  6-9 
listing  information, 

6-11  to  6-12 
OTS,  7-1  'o  7-2 
using  to   >solve  undefined 

global  symbols, 

6-8  to  6-9 
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Object  (Cont.) 
nodule, 

concatenated,  4-3  to  4-4 
FORTRAN  IV,  7-5  to  7-6 
input  to  TRB,  4-1 
MACRO-11,  1-4,  3-4  to  3-6 
Object  Time  System, 

See  OTS 
ODT  (On-Line  Debugging  Tool) , 
1-6  to  1-7 
at  sign  (9) ,  5-8 
B  command,  5-6 

backslash  character  (\) ,  5-5 
breakpoint  register,  5-6 
changing  location  contents, 

5-7 
correcting  input,  5-3 
dollar  sign  ($) ,  5-6  to  5-8 
error  conditions  in  task, 

5-8 
examining  locations, 

5-4  to  5-5 
forming  address,  5-4 
G  command,  5-6,  5-8 
including  in  a  task, 

5-1  to  5-2 
LINE  FEED  key,  5-5, 

5-7  to  5-8 
map  use,  5-2 
ODT. OBJ  file,  5-1 
P  command,  5-7 
question  mark  (?) ,  5-3 
R  command ,  5-3 
relocation  register, 

5-2  to  5-4 
RETURN  key,  5-8 
setting  breakpoints,  5-6 
setting  up  a  task  with,  1-7 
slash  character  (/) ,  5-4 
source  listing  use,  5-4 
SST  within,  5-8 
terminating  task  execution, 

5-8 
underline  character  (_) ,  3-2 
X  command,  5-8 
OLB  file  type,  6-4 
See  also  LBR 
On-Line  Debugging  Tool, 

See  ODT 
OTS  (Object  Tine  System) , 
library,  7-1  to  7-2 


P  command  (ODT) ,  5-7 
•PAGE  directive,  2-6 
PC  (Program  counter) , 
value,  4-8 


Peripheral  Interchange 
Program, 
See  PIP 
PIP  (Peripheral  Interchange 
Program) ,  1-8 
asterisk  (*) ,  3-10 
cleaning  up  a  UFD, 

3-9  to  3-10 
creating  a  concatenated 
object  module, 
4-3  to  4-4 
examining  listing  at 

terminal,  3-6,  4-6,  >  -4 
/LI,  3-9 
/ME,  4-3  to  4-4 
printing  listing,  3-8  to  3-9 
/PU,  3-10 
/SP,  3-8 

spooling  listing,  3-8  to  3  9 
PLOCATE  command  (EDI),  2-15 
.PMD  file  type,  5-10 

See  also  PMD 
PMD  (Postmortem  Dump) ,  1-7 

enabling  with  TKB,  5-9 
Postmorteni  Dump, 

See  PMD 
PRINT  command  (DCL) ,  1-12,  3-8 
PRINT  command  (MCR) ,  3-9 
Printer,  1-12 
Program, 

sectioning,  1-4  to  1-5,  2-5, 

2-8  to  2-9 
user, 

breakpoints, 

setting,  5-6 
FORTRAN  IV,  7-3 
library,  6-1 
macro  symbol,  6-4 

definition  placement, 
1-5 
module, 

name,  2-3,  2-5 
version,  2-5 
object  library  routines, 

6-6 
overview  of  development, 

1-13  to  1-14 
section  definiton, 

2-8  to  2-9 
system  routines,  1-11 
Program  counter. 

See  PC 
Programming, 
advanced, 

techniques,  1-6 
.PSECT  directive,  2-8  to  2-9 
PURGE  command  (DCL) ,  3-9 
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QMG  (Queue  Manager) ,  1-12 
Question  mark  (?) , 

ODT,  5-3 
Queue  Manager, 

See  QMG 


Record  Wanagenent  Services, 

See  RMS-11 
Register, 

breakpoint,  5-6 
relocation,  5-2  to  5-4 
Relocation  register, 

5-2  to  5-4 
RENEW  command  (EDI),  2-15 
RETURN  key, 

closing  location  (ODT) ,  5-5, 

5-8 
displaying  new  line  (EDI), 

2-13 
entering  text  (EDI) ,  2-9 
terminating  input  (EDI), 

2-9  to  2-10,  2-18,  7-7 
RMS-11  (Record  Management 
Services) , 
library,  1-9,  1-11 
RMSLIB.OLB  (Record  Management 

Services  library) ,  1-11 
RMSMAC.MLB  (Record  Management 

Services  library) ,  1-9 
RSXMAC.SML  (System  macro 
library) ,  l-5r 
1-9  to  1-10,  2-7 
RUN  command,  4-7,  5-2,  7-6 


.SBTTL  directive,  2-6 
Skeleton, 

source  file  (MACRC-11) ,  2-4 
Slash  character  (/) , 

EDI,  2-16 

ODT,  5-4 
$SNAP  (Snapshot  dump) , 

1-7  to  1-8,  5-9  to  5-10 

subset  of  Postmortem  Dump 
Task,  5-9  to  5-10 
Snapshot  dump. 

See  $SNAP 
Source  file  (FORTRAN  IV) , 

adding  debugging  statements, 
7-7 

blank  line,  7-3 

comment  line,  7-3 

creating,  7-2  to  7-3 

editing,  7-4  to  7-5,  7-7, 
7-9 


Source  file  (MACRO-11), 
assembling,  3-1  to  3-2 
creating  from  a  skeleton, 

2-12 
editing,  2-13  to  2-18 
error,  3-2  to  3-4 
format,  2-1  to  2-3 

skeleton,  2-4 
inserting  lines,  2-18 
listing,  3-4  to  3-6 
macro  library  call, 

6-3  to  6-4 
preface,  2-1 
SST  (Synchronous  system  trap) , 
ODT,  5-8 
relation  to  Postmortem  Dump, 

1-7 
role  in  task  termination, 
4-8  to  4-9 
Statement, 

MACRO-11,  1-4 
format,  2-3    ( 
Symbol, 

cross-reference,  3-7  to  3-8 
global,  1-5 

entry  point,  1-4 
resolution,  1-4  to  1-5, 
4-2 
local,  1-4  to  1-5,         i  ' 
2-7  to  2-8 
definition,  2-7  to  2-8 
macro, 

definition,  1-4,  1-10, 
2-7,  6-4 
MACRO-1'  valuation,  1-4, 
3-1  to  3-2 
Synchronous  system  trap. 

See  SST 
SYSLIB.OLB  (System  library), 

1-11 
System, 

directive,  1-9  to  1-10 
library, 

contributions  (in  map) , 

4-7 
macro  (RSXMAC.SML),  1-5, 
1-9  to  1-10 
contents,  1-9 
search,  1-5,  1-10,  2-7 
object  (SYSLIB.OLB),  i-11 
contents,  1-11 
search,  1-11,  4-2 
task,  1-1 


Task, 

abort,  4-8 


:5,«- 
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Task  (Cont.) 
brettkpolnta, 

setting,  5-6 
building,  4-1,  7-6 
correcting,  4-9 
dftbijgging,  4-9,  7-7  to  7-9 
default  conditions, 

4-4  to  4-5,  4-7  to  4-8 
macro  calls,  6-3  to  6-4 
'  map,  4-5 
full,  4-7 

standard,  4-5  to  4-6 
object  library  routines,  6-6 
running,  4-7  to  4-8,  7-6 
SST,  4-8 
system,  1-1 
bystem  library 

contributions,  4-7 
termination,  4-8 
transfer  (starting)  address, 
default,  4-3,  4-8 
defining,  2-7  .  • 

Task  Builder, 

See  7KB 
Task  image,  1-6,  4-1,  7-6 
creating,  4-1  to  4-2, 
7-5  to  7-6 
Task  Termination  and 
Notification, 
See  TKTN 
Terminal , 

examining  a   listing, 

3-6  to  ^-^ 

output, 

controlling,  3-7 
types,  1-12 
Text, 

buffer,  1-3 
editor,  1-3  to  1-4 
See  also  EDI,  EDT 
•TITLE  directive,  2-3,  2-5, 

6-7 
TKB  command  (MCR) ,  1-5,  4-1, 
5-2,  5-9,  6-7 
See  also  TKB 
TKB  (Task  Builder),  1-5  to  1-6 
/CR,  1-8,  4-6,  5-2 
/CROSSREFERENCE,  1-8,  4-5, 

5-1 
/DA,  5-2 
/DEBUG,  5-1 

error,  4-2,  4-8  to  4-9 
/FAST,  4-4 
fast  version,  4-4 
generating, 

cross-referance  listing, 

4-5  to  4-6 
map, 

full,  4-7 


TKB  (Task  Builder)  (Cont.) 
standard,  4-5  to  4-6 
/INCLUDE,  6-7  to  6-9 
input,  1-5  to  1-6 
/LB,  6-7  to  6-9,  7-8 
/LIBRARY,  6-8  to  6-9,  7-8 
LINK  command  (DCL) ,  1-5, 

4-1,  5-1,  5-9,  6-7 
/LONG,  *-7 
/MA,  4-7 
/MAP,  4-5,  4-7,  5-1,  5-9, 

6-7  to  6-9 
/NOTASK,  4-5 
/NOWIDE,  4-5 
object  library, 

designation,  6-4  to  6-5 
use,  6-8  to  6-9 
output,  1-6 
/PM,  5-9 

/POSTMORTEM,  5-9 
search  of  system  library, 

default,  1-11 
/-SH,  4-7 
symbol,  ' 

undefined,  4-2 
/SYSTEM  LIBRARYDISPLAY..  4-7 
/TASK,  I-l,  6-7  to  6-9 
TKB  command  (MCR),  1-5,  4-1, 

5-2,  5-9,  6-7 
transfer  (starting)  address, 

default,  4-3 
/-WI,  4-6 
TKTN  (Task  Termination  and 
Notification), 
abort  message,  4-8 
using  with  PMD,  1-7 
Transfer  (Starting)  address, 
defining,  2-7 

system  treatment  of  default, 
4-3,  4-8 
Trap, 

See  SST 
.TSK  file  type,  4-1 
TYPE  command  (DCL),  3-6,  4-6, 

7-4 
TYPE  command  (EDI) , 

2-13  to  2-14,  2-17 

Underline  character  (_) ,  DDT,  5-2 
Utility  programs,  1-8  to  1-9 

Virtual  memory  management, 

library,  1-11 
VMLIB.OLB  (Virtual  memory 

management  library) ,  1-11 


X  command  (ODT) ,  5-8 


Index-8 


RSX-llM/M-PLUS  Guide 

to  Program  Development 

AA-L676A-TC 


READER'S  COMMENTS 

NOTE:  This  form  is  for  document  comments  only.  DIGITAL  will  use  comments  submitted  on  this  form  at  the 
company's  discretion.  If  you  require  a  written  reply  and  are  eligible  to  receive  one  under  Software 
Performance  Report  (SPR)  service,  submit  your  comments  on  an  SPR  form. 


Did  you  find  this  manual  understandable,  usable,  and  well-organized?  Please  make  suggestions  for  improvement. 
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